home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 007 / advbas33.arc / ADVBAS.DOC < prev    next >
Text File  |  1987-04-15  |  107KB  |  4,896 lines
  1.  
  2.  
  3.  
  4.  
  5.  
  6.  
  7.  
  8.                 Advanced Function Library for the BASIC Compiler
  9.  
  10.  
  11.                             ADVBAS.LIB v3.3, 04/14/87
  12.  
  13.                    Copyright (C) Thomas Hanlin III, 1985-1987
  14.  
  15.  
  16.      Before June 1, 1987:
  17.        6812 Sydenstricker Rd
  18.        Springfield, VA 22152
  19.  
  20.      After June 1, 1987:
  21.        1712 Maple Hill Place
  22.        Alexandria, VA 22302
  23.  
  24.  
  25.  
  26.  
  27.      Requirements:
  28.  
  29.           An  IBM  PC  or compatible with the IBM BASIC Compiler v2.x or the
  30.      Microsoft  QuickBASIC  Compiler.   PC-DOS/MS-DOS versions 2.0 or higher
  31.      should  be  used.   Some  functions  may require a PC AT or compatible,
  32.      as noted.
  33.  
  34.  
  35.  
  36.      Copying and Distribution:
  37.  
  38.           ADVBAS  may  be  copied  and  distributed  freely  EXCEPT  FOR THE
  39.      ASSEMBLY  SOURCE  CODE.   If  you  distribute  ADVBAS on communications
  40.      systems  such  as  BBSes  or  CompuServe,  the  Source, et al, you must
  41.      include  a  minimum  of  the following unmodified files as a set (using
  42.      ARC   or  an  equivalent  archive  utility):   ADVBAS.EXE,  ADVBAS.LIB,
  43.      ADVBAS.DOC,  ADVBAS.NEW,  ADVBAS.QRF,  ADVBAS.ERR, CONTRIB.DOC.  No fee
  44.      other than a disk and handling charge (of up to $10) may be charged.
  45.  
  46.           The  copyright  is to preserve my options, and to protect you from
  47.      the  untoward  modifications  of others.  It is not intended to prevent
  48.      the public distribution of ADVBAS, subject to the above limitations.
  49.  
  50.  
  51.  
  52.  
  53.  
  54.  
  55.  
  56.  
  57.  
  58.  
  59.  
  60.  
  61.  
  62.  
  63.  
  64.  
  65.  
  66.  
  67.  
  68.  
  69.  
  70.  
  71.  
  72.  
  73.  
  74.      Introduction:
  75.  
  76.           The  BASIC  Compiler  is  a  powerful and flexible tool.  However,
  77.      it  suffers  from  a  number of limitations.  It is hard to access many
  78.      of  the  capabilities of DOS; any feature which requires error trapping
  79.      cannot  be  used  in  a  subprogram; the memory requirements are fairly
  80.      substantial;  and  the  speed  is not all that it might be, for all its
  81.      improvement  over  interpreted  BASIC.   To reduce these problems, I've
  82.      designed  a  number of assembly language routines which perform various
  83.      functions,  and  put  them  in a library which the compiler can access.
  84.      Since  I  have  found  these functions to be useful, I thought I'd pass
  85.      them  on  to other people.  You may use ADVBAS functions in any of your
  86.      programs.   I'd appreciate it if you acknowledged use of these routines
  87.      in your program or documentation.
  88.  
  89.           If  you  find  ADVBAS useful, please support the author's efforts!
  90.      A minimum contribution of $25 will get you a disk containing the latest
  91.      version  of  ADVBAS, including source and object code.  The latest ver-
  92.      sion  of  ADVBAS  is always available to previous contributors for only
  93.      $10.
  94.  
  95.  
  96.  
  97.      Support:
  98.  
  99.           If  you  are  a  contributor  (bless you!), I'll certainly be glad
  100.      to  help  you  with  any  difficulties you may encounter.  U.S. Mail is
  101.      the  preferred  method  of  exchange,  but  feel  free  to  call if the
  102.      situation gets out of hand.
  103.  
  104.           If  you  are  not  a  contributor  (sigh), please send a SASE, and
  105.      I'll  get  back  to  you.   Do  not phone!  If you don't care enough to
  106.      contribute  the  minimal fee I ask, you should not expect me to provide
  107.      services.  TANSTAAFL!  (There Ain't No Such Thing As A Free Lunch)
  108.  
  109.  
  110.  
  111.      Caveats:
  112.  
  113.           These  functions  have  not  caused  me  any problems, and seem to
  114.      be  fully debugged.  However, I will not be responsible for any damages
  115.      caused by use, misuse, or inability to use ADVBAS.
  116.  
  117.  
  118.  
  119.  
  120.  
  121.  
  122.  
  123.  
  124.  
  125.  
  126.  
  127.  
  128.  
  129.  
  130.  
  131.  
  132.  
  133.  
  134.  
  135.  
  136.  
  137.  
  138.  
  139.  
  140.      Using ADVBAS with QuickBASIC v2.0+:
  141.  
  142.           If  you  use  QuickBASIC  in  the new programming environment, you
  143.      need  to  have  a  copy  of  ADVBAS.EXE in the drive/subdirectory where
  144.      you  keep  your  library  files  (like  BRUN20.LIB).  When you start up
  145.      QuickBASIC,  you  need  to  tell  it  to load the ADVBAS library so you
  146.      can  use  its  features.  Run QuickBASIC with the following syntax: "QB
  147.      /L  ADVBAS.EXE".   Alternately,  you  can specify a program filename as
  148.      well: "QB  PROGRAM.BAS  /L  ADVBAS.EXE".   You can leave off the ".BAS"
  149.      extension  to  the  program,  but  you can't leave the ".EXE" extension
  150.      off  ADVBAS.EXE.   Note  that  you are not meant to type in the quotes,
  151.      which  are  there  for  guidance  only.  You may also need to include a
  152.      drive/path  spec  for  ADVBAS  if  it is in a different drive/path than
  153.      the default.  That might look something like "QB /L B:ADVBAS.EXE".
  154.  
  155.  
  156.  
  157.      Using IBM or Microsoft BASIC compilers (command-line mode):
  158.  
  159.           Copy  ADVBAS.LIB to the disk on which you keep your BASIC Compiler
  160.      library files.  For programs which use ADVBAS functions, specify ADVBAS
  161.      when  LINK  asks  you  which  libraries to use.  That is, at the LINKer
  162.      prompt  "Libraries  [.LIB]:"  you  should  say  "ADVBAS"  (without  the
  163.      quotes!).   You  may  need to provide a drive/path spec if your program
  164.      is  not  in  the  same area that ADVBAS is, and if you don't have a SET
  165.      LIB  in  your  autoexec  file to tell the compiler where the library is
  166.      (only newer versions of the compilers have this feature). 
  167.  
  168.  
  169.  
  170.      Other languages:
  171.  
  172.           A  version  of  ADVBAS  is  in  progress for the BASIC Interpreter
  173.      (BASICA or GWBASIC).
  174.           A version of ADVBAS is progress for the Turbo BASIC compiler.
  175.           A  library  for  Microsoft  C is available under the name of ADVC.
  176.      It  is  in  C  source  format, so you can convert any nonstandard func-
  177.      tions  to  your  own  variety of C.  If you can't find it on your local
  178.      BBS,  I'll  send  you  a  copy for the recommended minimum contribution
  179.      of $15.  Updates are not anticipated.
  180.  
  181.  
  182.  
  183.      Advantages of ADVBAS:
  184.  
  185.           1) Adds abilities which are not otherwise available.
  186.           2) Is faster than the corresponding Compiled BASIC code.
  187.           3) Usually takes up less space in the resulting EXEcutable file.
  188.           4) Often leaves more free programming space.
  189.           5) Provides a useful library of tested low-level routines.
  190.  
  191.  
  192.  
  193.  
  194.  
  195.  
  196.  
  197.  
  198.  
  199.  
  200.  
  201.  
  202.  
  203.  
  204.  
  205.  
  206.                                  Operation Notes
  207.  
  208.  
  209.  
  210.  
  211.      Function Requirements:
  212.  
  213.           Numeric  variables  used in function calls must be integers unless
  214.      specified  otherwise.   Either declare them using DEFINT, or add a per-
  215.      cent sign "%" to the end of the variable name.
  216.  
  217.           Strings  must  sometimes  be  defined to a certain minimum length,
  218.      due  to  limitations  on  what  assembly  language routines are allowed
  219.      to do to strings. 
  220.  
  221.           Dynamic Arrays are NOT SUPPORTED.  Use only normal (Static) arrays
  222.      when  a  function  requires  an  array.   Dynamic arrays are not passed
  223.      to  called  routines  in  any  sensible manner, but I'll try to come up
  224.      with some way to handle 'em in a future version of ADVBAS.
  225.  
  226.  
  227.  
  228.      Compatibility:
  229.  
  230.           These  functions  vary in what they demand of your PC.  Some func-
  231.      tions  will  work only on IBM PCs or clones, some will work on compati-
  232.      bles,  and  some  will  work  on any MS-DOS routine.  The compatibility
  233.      level  of each function is now listed, using the categories CLONE (will
  234.      work  on  hardware  compatibles  only),  BIOS  (close compatibles), DOS
  235.      (any  MS-DOS  machine), and ANY (hardware independent).  Be warned that
  236.      the  BASIC  Compiler  itself  does  not produce particularly compatible
  237.      code (BASIC video routines seem to be BIOS-compatible, etc).
  238.  
  239.  
  240.      QuickBASIC 2.0+:
  241.  
  242.           See  the operation notes at the beginning of this document.  Other
  243.      than that, all functions should work as expected in either command-line
  244.      or programming-environment modes.
  245.  
  246.  
  247.  
  248.  
  249.  
  250.  
  251.  
  252.  
  253.  
  254.  
  255.  
  256.  
  257.  
  258.  
  259.  
  260.  
  261.  
  262.  
  263.  
  264.  
  265.  
  266.  
  267.  
  268.  
  269.  
  270.  
  271.  
  272.                                 Routine Reference
  273.  
  274.  
  275.  
  276.  
  277.      Disk:
  278.           CopyFile:  copy a file
  279.           DelSub, GetSub, MakeSub, SetSub:  subdirectory handling
  280.           DiskStat:  assorted disk status information
  281.           DrvSpace:  space left on a given drive
  282.           Exist:  see if a file exists
  283.           Fclose, Fcreate, Fopen, Fread, FsetEnd, FsetRec, Fclose:
  284.              file i/o
  285.           FindFirstF, FindNextF:  handle file(s) with wildcards
  286.           GetDrv, SetDrv:  get/set the default drive
  287.           GetFdate, GetFtime, SetFTD, GetFattr, SetFattr:  file info control
  288.           GetNameF, GetDateF, GetTimeF, GetAttrF, GetSizeF: file dir control
  289.           Mload:  a BLOAD routine
  290.           SubExist:  see if a subdirectory exists
  291.  
  292.      Input:
  293.           ClrKbd:  clear the keyboard buffer of pending keys
  294.           DosInkey:  get a key using DOS standard input
  295.           GetKbd, SetKbd:  get/set the status of the keyboard toggles
  296.           GetKey:  get one of a list of valid keys
  297.           KeyPress:  see if a key has been pressed
  298.  
  299.           MMcursorOn, MMcursorOff:         mouse cursor control
  300.           MMgetloc, MMsetloc, MMsetrange:  mouse display control
  301.           MMbutton, MMcheck, MMclick:      mouse status info
  302.  
  303.      String:
  304.           Bsq, BusqLen, Busq:  text compression/decompression
  305.           Checksum, CRC:  error checking (for telecomm and other uses)
  306.           DateN2S, DateS2N:  convert the date (numbers <--> string)
  307.           Extract:  take delimited substrings from a string using an index
  308.           Locase, Upcase:  case conversion
  309.           MultiAnd, MultiOr, MultiXor:  bit manipulations on strings
  310.           Strip, StripBlanks, StripRange:  deletion of chars from a string
  311.           LRotate, RRotate, Reverse:  reorder chars in a string
  312.           Soundex:  return the Soundex code of a string
  313.           TimeN2S, TimeS2N:  convert the time (numbers <--> string)
  314.           Tinstr:  find a given type of char within a string
  315.           Xlate:  run the chars of a string through a translation table
  316.  
  317.  
  318.  
  319.  
  320.  
  321.  
  322.  
  323.  
  324.  
  325.  
  326.  
  327.  
  328.  
  329.  
  330.  
  331.  
  332.  
  333.  
  334.  
  335.  
  336.  
  337.  
  338.                                 Routine Reference
  339.  
  340.  
  341.  
  342.  
  343.      Array:
  344.           AddMatI, SetMatI:  integer array manipulation
  345.           ReadBitF, WriteBitF:  handle arrays of arbitrary bit length
  346.  
  347.      Video:
  348.           CalcAttr:  calculate attribute from fore and background colors
  349.           DMprint, Mprint, MprintC, Qprint, XQprint:  various print routines
  350.           ClrEol, BkSpace, DelChr, InsChr, MDelChr, MInsChr:  screen control
  351.           GetCRT:  get display type (mono or color)
  352.           MakeWindow:  make pop-up windows
  353.           Mwindow, Scroll, BkScroll:  display window control
  354.           PrintScreen:  print out the display to the default printer
  355.           ScrSave, ScrRest, GetLine:  save/restore the contents of a screen
  356.           ScrSaveP, ScrSavePD, ScrRestP, ScrRestPD:  variants on the above
  357.           GetScreen, PutScreen:  new flexible screen save/restore routines
  358.           ReColor: change any screen color to another w/o clearing screen
  359.           ResetPoint, SetPoint, TestPoint:  low-res graphics in text mode
  360.  
  361.      Miscellaneous:
  362.           Any2Dec, Dec2Any:  radix conversion (decimal <--> another base)
  363.           BlockMove:  move data from one area of memory to another
  364.           Carrier:  check modem Carrier Detect signal
  365.           DataSeg:  return the value of the default Data Segment
  366.           Date2int, Int2date:  date compression
  367.           Delay, Delay18th:  delay for a given amount of time
  368.           DTR:  turn the communications line "DTR" on or off
  369.           Equipment:  get hardware info about memory and installed ports
  370.           GetDOSv:  get the version number of the MS-DOS being used
  371.           GetExtM:  return the amount of extended memory (AT systems only)
  372.           GetLIMM:  get the status of expanded memory in the system
  373.           Month:  given a month number, returns the name of the month
  374.           SetComm:  set up any comm port to any baud, without closing comm
  375.           ShiftL, ShiftR:  bit shifts for integers
  376.           Speaker:  turns sound effects on or off
  377.           Time2int, Int2time:  time compression
  378.           WeekDay:  returns the day of the week, Sunday through Saturday
  379.  
  380.  
  381.  
  382.  
  383.  
  384.  
  385.  
  386.  
  387.  
  388.  
  389.  
  390.  
  391.  
  392.  
  393.  
  394.  
  395.  
  396.  
  397.  
  398.  
  399.  
  400.  
  401.  
  402.  
  403.  
  404.                                Compatibility Chart
  405.  
  406.  
  407.  
  408.  
  409.      Works on ANY machine:
  410.  
  411.           ADDMATI,   ANY2DEC,   BLOCKMOVE,  BSQ,  BUSQ,  BUSQLEN,  CALCATTR,
  412.      CHECKSUM,  CRC, DATASEG, DATE2INT, DEC2ANY, EXTRACT, GETLINE, INT2DATE,
  413.      INT2TIME,   LOCASE,   LROTATE,   MONTH,  MULTIAND,  MULTIOR,  MULTIXOR,
  414.      READBITF,  REVERSE,  RROTATE,  SETMATI, SHIFTL, SHIFTR, SOUNDEX, STRIP,
  415.      STRIPBLANKS, STRIPRANGE, TIME2INT, TINSTR, UPCASE, WRITEBITF, XLATE
  416.  
  417.  
  418.  
  419.      Works on DOS compatibles:
  420.  
  421.           COPYFILE,  DELSUB,  DISKSTAT,  DMPRINT, DOSINKEY, DRVSPACE, EXIST,
  422.      FCLOSE, FCREATE, FINDFIRSTF, FINDNEXTF, FOPEN, FREAD, FSETEND, FSETREC,
  423.      FWRITE,   GETATTRF,  GETDATEF,  GETDOSV,  GETDRV,  GETFATTR,  GETFDATE,
  424.      GETFTIME, GETNAMEF, GETSIZEF, GETSUB, GETTIMEF, MAKESUB, MLOAD, SETDRV,
  425.      SETFATTR, SETFTD, SETSUB, SUBEXIST, WEEKDAY
  426.  
  427.  
  428.  
  429.      Works on BIOS compatibles (* if it requires the AT BIOS):
  430.  
  431.           BKSCROLL,  BKSPACE,  CARRIER,  CLRKBD,  CLREOL,  DATEN2S, DATES2N,
  432.      DELAY,   DELAY18TH,   EQUIPMENT,  GETCRT,  GETEXTM*,  GETKEY,  GETLIMM,
  433.      KEYPRESS,  MDELCHR,  MINSCHR,  MMBUTTON, MMCHECK, MMCLICK, MMCURSOROFF,
  434.      MMCURSORON,  MMGETLOC,  MMSETLOC, MMSETRANGE, MPRINT, MPRINTC, MWINDOW,
  435.      PRINTSCREEN, RESETPOINT, SETPOINT, SCROLL, TESTPOINT, TIMEN2S, TIMES2N,
  436.      XMPRINT
  437.  
  438.  
  439.  
  440.      Works on CLONEs (hardware compatibles):
  441.  
  442.           DELCHR,  DTR,  GETKBD,  GETSCREEN,  INSCHR, MAKEWINDOW, PUTSCREEN,
  443.      QPRINT,  RECOLOR,  SCRREST,  SCRRESTP,  SCRRESTPD,  SCRSAVE,  SCRSAVEP,
  444.      SCRSAVEPD, SETCOMM, SETKBD, SPEAKER, XQPRINT, XQPRINTD
  445.  
  446.  
  447.  
  448.           Note  that  routines  from  higher  sections will work on machines
  449.      from  lower  sections  (DOS-level  routines  will  work  on  BIOS-  and
  450.      CLONE-level   machines).    It   doesn't  work  the  other  way  around
  451.      (CLONE-level routines may not work on a DOS-level machine).
  452.  
  453.  
  454.  
  455.  
  456.  
  457.  
  458.  
  459.  
  460.  
  461.  
  462.  
  463.  
  464.  
  465.  
  466.  
  467.  
  468.  
  469.  
  470.      Name: ADDMATI
  471.  
  472.      Type: Miscellaneous / ANY
  473.  
  474.      Description:
  475.           Adds a scalar (integer) value to the first SIZ elements of an
  476.      integer  array.   You  can  subtract  by  adding a negative number.  If
  477.      the  results  of  the calculation ever go outside integer range (-32768
  478.      to 32767), the
  479.      overflow flag is set on return.  See SETMATI for more information.
  480.  
  481.      Example:
  482.           DEFINT A-Z: OPTION BASE 1: DIM ACK(10000): SIZ=10000
  483.            .
  484.            .
  485.           ADDVAL=-6: ARLOC=VARPTR(ACK(1))
  486.           CALL ADDMATI(ARLOC,SIZ,ADDVAL,OVFLOW)
  487.           IF OVFLOW THEN PRINT"Uh oh, overflowed somewhere..."
  488.           REM  we just subtracted six from each element of the array ACK.
  489.  
  490.  
  491.  
  492.  
  493.      Name: ANY2DEC
  494.  
  495.      Type: Miscellaneous / ANY
  496.  
  497.      Description:
  498.           Converts  a  number  (in  string  form)  from any base (2-35) to a
  499.      decimal integer (base 10).  The number to be converted may be in either
  500.      signed  integer  range  (-32768  to 32767) or unsigned integer range (0
  501.      to  65535).   It  is  converted  to a signed integer, which is the only
  502.      integer type BASIC supports.
  503.  
  504.      Example:
  505.           INPUT"Number, base of number";ANUM$,NBASE
  506.           CALL ANY2DEC(ANUM$,NBASE,DNUM,ERCD)
  507.           IF ERCD THEN PRINT"Bad number!" ELSE PRINT"Decimal: ";DNUM
  508.  
  509.  
  510.  
  511.  
  512.  
  513.  
  514.  
  515.  
  516.  
  517.  
  518.  
  519.  
  520.  
  521.  
  522.  
  523.  
  524.  
  525.  
  526.  
  527.  
  528.  
  529.  
  530.  
  531.  
  532.  
  533.  
  534.  
  535.  
  536.      Name: BLOCKMOVE
  537.  
  538.      Type: Miscellaneous / ANY
  539.  
  540.      Description:
  541.           Copies information from one area of memory to another.  You supply
  542.      the  source  segment and offset, destination segment and offset, number
  543.      of  bytes  to  move (0 - 65535), and direction (zero, forward; nonzero,
  544.      backward).   This  can be used, for instance, to duplicate arrays (with
  545.      the assistance of the DATASEG function and BASIC's VARPTR function).
  546.  
  547.      Example:
  548.           CALL BLOCKMOVE(FROMSEG,FROMOFFSET,TOSEG,TOOFFSET,BYTES,DIRECTION)
  549.  
  550.  
  551.  
  552.  
  553.      Name: BKSCROLL
  554.  
  555.      Type: Video / BIOS
  556.  
  557.      Description:
  558.           The  same  as  SCROLL  (q.v.),  but  scrolls lines in the opposite
  559.      direction (Back Scroll).
  560.  
  561.      Example:
  562.           CALL BKSCROLL(LEFTCOL,TOPROW,RTCOL,BOTROW,NUMLINES)
  563.  
  564.  
  565.  
  566.  
  567.  
  568.  
  569.  
  570.  
  571.  
  572.  
  573.  
  574.  
  575.  
  576.  
  577.  
  578.  
  579.  
  580.  
  581.  
  582.  
  583.  
  584.  
  585.  
  586.  
  587.  
  588.  
  589.  
  590.  
  591.  
  592.  
  593.  
  594.  
  595.  
  596.  
  597.  
  598.  
  599.  
  600.  
  601.  
  602.      Name: BKSPACE
  603.  
  604.      Type: Video / BIOS
  605.  
  606.      Description:
  607.           Move  cursor back one space, destroying the character on the space
  608.      moved  to.   Will  wrap  from one line to the next higher if necessary.
  609.      If  at  the  top  left  corner  of  the screen, no action is performed.
  610.      Two  arguments  return  the  new  cursor coordinates.  Works with 40 or
  611.      80 column screens in text mode.
  612.  
  613.      Example:
  614.           CALL BKSPACE(COL,ROW) : LOCATE ROW,COL
  615.  
  616.  
  617.  
  618.  
  619.      Name: BSQ
  620.  
  621.      Type: String / ANY
  622.  
  623.      Description:
  624.           Uses  several  techniques to compress blank spaces out of an ASCII
  625.      string.   Savings  range  from  16% (reliable, for ordinary text) to up
  626.      around 50% or more for space-intensive info, such as lines in an assem-
  627.      bly  source  file.   BSQ  cannot  handle  more than 127 spaces in a row
  628.      on  a  single  line,  or  lines  which contain ASCII characters greater
  629.      than  127  (which  are  IBM-specific  graphics characters).  Do not use
  630.      BSQ  on  lines  which  may  contain  such information!  BSQ compression
  631.      is  designed  to  produce printable (if odd-looking) text which you may
  632.      read/write to ordinary sequential files.
  633.  
  634.      Example:
  635.           INPUT"String to squeeze";ST$: CALL BSQ(ST$,SLEN)
  636.           PRINT"Squeezed string: ";LEFT$(ST$,SLEN)
  637.  
  638.  
  639.  
  640.  
  641.      Name: BUSQ
  642.  
  643.      Type: String / ANY
  644.  
  645.      Description:
  646.           Decompresses  a  line  squeezed  by  BSQ.  Use BUSQLEN before this
  647.      routine to find out how long the unsqueezed line will be!
  648.  
  649.      Example:
  650.           see BUSQLEN
  651.  
  652.  
  653.  
  654.  
  655.  
  656.  
  657.  
  658.  
  659.  
  660.  
  661.  
  662.  
  663.  
  664.  
  665.  
  666.  
  667.  
  668.      Name: BUSQLEN
  669.  
  670.      Type: String / ANY
  671.  
  672.      Description:
  673.           Tells  how  long  a  line  squeezed  with  BSQ  will  be once it's
  674.      unsqueezed.  You must use this before unsqueezing the line with BUSQ.
  675.  
  676.      Example:
  677.           CALL BUSQLEN(ST$,SLEN)
  678.           IF SLEN<0 THEN line not squeezed, or damaged-- exit!
  679.           ELSE UNSQ$=SPACE$(SLEN): CALL BUSQ(ST$,UNSQ$)
  680.  
  681.  
  682.  
  683.  
  684.      Name: CALCATTR
  685.  
  686.      Type: Video / ANY
  687.  
  688.      Description:
  689.           Calculates  the  color  attribute  for  such  routines as XQPRINT.
  690.      Unlike  the  BASIC  formula  it  replaces,  CALCATTR  allows use of the
  691.      "blink" attribute.
  692.  
  693.      Example:
  694.           REM  old formula was  ATTR = (BACKGND AND 7)*16 + FOREGND
  695.           CALL CALCATTR(FOREGND,BACKGND,ATTR)
  696.  
  697.  
  698.  
  699.  
  700.      Name: CARRIER
  701.  
  702.      Type: Miscellaneous / BIOS
  703.  
  704.      Description:
  705.           Returns  the  status  of the modem Carrier Detect signal.  You may
  706.      specify communications port one or two.
  707.  
  708.      Example:
  709.           COMMPORT = 1
  710.           CALL CARRIER(COMMPORT,CDSTATUS)
  711.           IF CDSTATUS THEN PRINT "Carrier detected" ELSE PRINT "No carrier"
  712.  
  713.  
  714.  
  715.  
  716.  
  717.  
  718.  
  719.  
  720.  
  721.  
  722.  
  723.  
  724.  
  725.  
  726.  
  727.  
  728.  
  729.  
  730.  
  731.  
  732.  
  733.  
  734.      Name: COPYFILE
  735.  
  736.      Type: Disk / DOS
  737.  
  738.      Description:
  739.           Copies a file.  This is faster than the corresponding DOS command,
  740.      and  doesn't  have  the  overhead of using the SHELL command.  Note: to
  741.      avoid  possibly  wiping  out  an  existing file on the destination end,
  742.      you may wish to use the EXIST function before this one.
  743.           The  copy  will  usually  fail  for one of two reasons: the source
  744.      file  doesn't  exist,  or  there is not enough room on the disk for the
  745.      destination file.
  746.  
  747.      Example:
  748.           SOURCE$ = "A:EXAMPLE.TXT" + CHR$(0)
  749.           DESTINATION$ = "C:\DOCUMENT\EXAMPLE.TXT" + CHR$(0)
  750.           CALL COPYFILE(SOURCE$,DESTINATION$,ERRCODE)
  751.           IF ERRCODE THEN PRINT"The copy failed"
  752.  
  753.  
  754.  
  755.  
  756.  
  757.  
  758.  
  759.  
  760.  
  761.  
  762.  
  763.  
  764.  
  765.  
  766.  
  767.  
  768.  
  769.  
  770.  
  771.  
  772.  
  773.  
  774.  
  775.  
  776.  
  777.  
  778.  
  779.  
  780.  
  781.  
  782.  
  783.  
  784.  
  785.  
  786.  
  787.  
  788.  
  789.  
  790.  
  791.  
  792.  
  793.  
  794.  
  795.  
  796.  
  797.  
  798.  
  799.  
  800.      Name: CHECKSUM
  801.  
  802.      Type: Miscellaneous / ANY
  803.  
  804.      Description:
  805.           Calculates  a  checksum  for  a  record.   Can be used with Xmodem
  806.      or Ymodem.
  807.  
  808.      Example:
  809.           CALL CHECKSUM(REC$,CHKSM)
  810.  
  811.  
  812.  
  813.  
  814.      Name: CLREOL
  815.  
  816.      Type: Video / BIOS
  817.  
  818.      Description:
  819.           Clears  from  the  cursor  position to the end of the line without
  820.      moving the cursor.
  821.  
  822.      Example:
  823.           CALL CLREOL
  824.  
  825.  
  826.  
  827.  
  828.      Name: CLRKBD
  829.  
  830.      Type: Input / BIOS
  831.  
  832.      Description:
  833.           Clears any pending keys from the keyboard buffer.
  834.  
  835.      Example:
  836.           CALL CLRKBD
  837.           INPUT"File not found.  Continue (Y/N)";ANS$
  838.  
  839.  
  840.  
  841.  
  842.  
  843.  
  844.  
  845.  
  846.  
  847.  
  848.  
  849.  
  850.  
  851.  
  852.  
  853.  
  854.  
  855.  
  856.  
  857.  
  858.  
  859.  
  860.  
  861.  
  862.  
  863.  
  864.  
  865.  
  866.      Name: CRC
  867.  
  868.      Type: Miscellaneous / ANY
  869.  
  870.      Description:
  871.           Calculates  a  cyclical redundancy check value for a record.  This
  872.      is  useful  for  error  detection,  and  can be used with Xmodem CRC or
  873.      Ymodem CRC modem transfer protocols.
  874.  
  875.      Example:
  876.        Sending a record:
  877.           REC$=REC$+STRING$(2,0) : CALL CRC(REC$,HICRC,LOCRC) :
  878.           MID$(REC$,LEN(REC$)-1,2)  =  CHR$(HICRC)+CHR$(LOCRC) : send Xmodem
  879.      record
  880.        Receiving a record:
  881.           CALL CRC(REC$,HICRC,LOCRC) : IF HICRC=0 AND LOCRC=0
  882.                THEN record is fine, save it
  883.                ELSE record is bad, request it to be sent again
  884.  
  885.  
  886.  
  887.  
  888.  
  889.  
  890.  
  891.  
  892.  
  893.  
  894.  
  895.  
  896.  
  897.  
  898.  
  899.  
  900.  
  901.  
  902.  
  903.  
  904.  
  905.  
  906.  
  907.  
  908.  
  909.  
  910.  
  911.  
  912.  
  913.  
  914.  
  915.  
  916.  
  917.  
  918.  
  919.  
  920.  
  921.  
  922.  
  923.  
  924.  
  925.  
  926.  
  927.  
  928.  
  929.  
  930.  
  931.  
  932.      Name: DATASEG
  933.  
  934.      Type: Miscellaneous / ANY
  935.  
  936.      Description:
  937.           Returns  BASIC's  data  segment.   This  is  useful for BLOCKMOVE,
  938.      among other things.
  939.  
  940.      Example:
  941.           CALL DATASEG(DSEG)
  942.  
  943.  
  944.  
  945.  
  946.      Name: DATE2INT
  947.  
  948.      Type: Miscellaneous / ANY
  949.  
  950.      Description:
  951.           Compresses  a  date  down  to  a single integer, to reduce storage
  952.      requirements.   The  date  is  assumed to be valid.  The year should be
  953.      within  the  range  1900-2026  (0-99  is  ok,  and  is  assumed  to  be
  954.      1900-1999).  See also INT2DATE.
  955.  
  956.      Example:
  957.           CALL DATE2INT(MONTH,DAY,YEAR,SQZDATE)
  958.  
  959.  
  960.  
  961.  
  962.      Name: DATEN2S
  963.  
  964.      Type: String / ANY
  965.  
  966.      Description:
  967.           Converts the date from numeric form to a string.  You must reserve
  968.      at least eight characters for the string.
  969.  
  970.      Example:
  971.           MONTH = 3: DAY = 2: YEAR = 1987: REM  We could use MONTH=87 here
  972.           DAT$ = SPACE$(8)
  973.           CALL DATEN2S(MONTH,DAY,YEAR,DAT$)
  974.           REM  From this, we will get DAT$ = "03/02/87"
  975.  
  976.  
  977.  
  978.  
  979.  
  980.  
  981.  
  982.  
  983.  
  984.  
  985.  
  986.  
  987.  
  988.  
  989.  
  990.  
  991.  
  992.  
  993.  
  994.  
  995.  
  996.  
  997.  
  998.      Name: DATES2N
  999.  
  1000.      Type: String / ANY
  1001.  
  1002.      Description:
  1003.           Converts  the date from a string to numeric form.  The date string
  1004.      may   be  in  either  BASIC  format  ("03-15-1987")  or  normal  format
  1005.      ("03/15/87").
  1006.  
  1007.      Example:
  1008.           CALL DATES2N(MONTH,DAY,YEAR,DATE$)
  1009.  
  1010.  
  1011.  
  1012.  
  1013.      Name: DEC2ANY
  1014.  
  1015.      Type: Miscellaneous / ANY
  1016.  
  1017.      Description:
  1018.           Converts  a  number  from  decimal  (base  10)  to  any other base
  1019.      (2-35).   The  number  will be converted to an unsigned integer (signed
  1020.      range of -32768 to 32767 is converted to unsigned range of 0 to 65535),
  1021.      to  conform with the built-in BASIC conversion functions HEX$ and OCT$.
  1022.      ANUM$  must be initialized to the maximum size you expect the resultant
  1023.      number  to  be;  this  is recommended to be 16 characters, which is the
  1024.      maximum  length  possible.   The result is right-justified in the field
  1025.      you  provide,  so  if  you want to keep leading zeroes, just ignore the
  1026.      actual-length specification ALEN.
  1027.  
  1028.      Example:
  1029.           INPUT"Decimal number, to base";DNUM,NBASE
  1030.           ANUM$ = STRING$(16,"0"): CALL DEC2ANY(DNUM,NBASE,ANUM$,ALEN)
  1031.           IF ALEN<0 THEN PRINT"Bad base or ANUM$ initialized too short"
  1032.           ELSE PRINT"Result: ";RIGHT$(ANUM$,ALEN)
  1033.  
  1034.  
  1035.  
  1036.  
  1037.  
  1038.  
  1039.  
  1040.  
  1041.  
  1042.  
  1043.  
  1044.  
  1045.  
  1046.  
  1047.  
  1048.  
  1049.  
  1050.  
  1051.  
  1052.  
  1053.  
  1054.  
  1055.  
  1056.  
  1057.  
  1058.  
  1059.  
  1060.  
  1061.  
  1062.  
  1063.  
  1064.      Name: DELAY
  1065.  
  1066.      Type: Miscellaneous / BIOS
  1067.  
  1068.      Description:
  1069.           Delays for a given number of seconds.  This is based on the system
  1070.      clock,  and  will  delay  for  the  same  amount  of time on an 8088 or
  1071.      80286-based  computer.   It  is  normally  accurate to within about one
  1072.      percent.
  1073.  
  1074.      Example:
  1075.           SECONDS=60
  1076.           CALL DELAY(SECONDS)
  1077.           REM  sit and "do nothing" for one minute
  1078.  
  1079.  
  1080.  
  1081.  
  1082.      Name: DELAY18TH
  1083.  
  1084.      Type: Miscellaneous / BIOS
  1085.  
  1086.      Description:
  1087.           Delays  for  a given number of eighteenths of seconds.  Otherwise,
  1088.      this is identical to DELAY (see).
  1089.  
  1090.      Example:
  1091.           MINIDELAY=9
  1092.           CALL DELAY18TH(MINIDELAY)
  1093.           REM  delay for half a second (9/18 = 1/2 second)
  1094.  
  1095.  
  1096.  
  1097.  
  1098.      Name: DELCHR
  1099.  
  1100.      Type: Video / CLONE
  1101.  
  1102.      Description:
  1103.           Deletes  a  character  from  the specified location on the screen.
  1104.      The  character  at  that  location  will  disappear, and all characters
  1105.      to  the  right  of  it on the same screen line will be shifted left one
  1106.      space.   The  first  page  only  (on  color monitors) is supported, and
  1107.      text mode is required.
  1108.  
  1109.      Example:
  1110.           COL = POS(0): ROW = CSRLIN
  1111.           CALL DELCHR(ROW,COL)
  1112.  
  1113.  
  1114.  
  1115.  
  1116.  
  1117.  
  1118.  
  1119.  
  1120.  
  1121.  
  1122.  
  1123.  
  1124.  
  1125.  
  1126.  
  1127.  
  1128.  
  1129.  
  1130.      Name: DELSUB
  1131.  
  1132.      Type: Disk / DOS
  1133.  
  1134.      Description:
  1135.           Deletes  a  subdirectory.   Parameters  used  are  the  same as in
  1136.      SETSUB.   Note  that  you  may  not delete a subdirectory if it has any
  1137.      files  left  in  it,  or  if  it is the main directory, or if it is the
  1138.      current default subdirectory.
  1139.  
  1140.      Example:
  1141.           TMP$ = SUB$+CHR$(0): CALL DELSUB(TMP$,ERRCODE)
  1142.           IF ERRCODE THEN couldn't delete subdir ELSE subdir deleted
  1143.  
  1144.  
  1145.  
  1146.  
  1147.      Name: DISKSTAT
  1148.  
  1149.      Type: Disk / DOS
  1150.  
  1151.      Description:
  1152.           Returns  status  information  for  a  given disk drive.  The drive
  1153.      spec should be a letter, or use "@" for the default drive.  Information
  1154.      returned  will  be  Free  Clusters,  Total  Clusters, Bytes per Sector,
  1155.      and  Sectors  per Cluster.  This will enable you to calculate the total
  1156.      space  on  the  disk,  free  space  left on the disk, the actual amount
  1157.      of  space  a  file  takes up, and so forth.  A "cluster" is the minimum
  1158.      block  of  space  that  can  be allocated on a disk.  The actual amount
  1159.      of  space  taken  up  by  a  file  depends on the cluster size.  If the
  1160.      cluster  size  is  1024 bytes, any file that is listed as being between
  1161.      1  and  1024  bytes  will  take  up 1024 bytes of disk space.  Any file
  1162.      listed  as  having  1025  -  2047 bytes will take up 2048 bytes (1024 *
  1163.      2), and so on.
  1164.  
  1165.      Example:
  1166.           DRIVE$ = "@":  REM  Use the default drive
  1167.           CALL DISKSTAT(DRIVE$,FREE.CLUST,TOTAL.CLUST,BYTES.SEC,SECS.CLUST)
  1168.           CLUSTER.SIZE# = CDBL(BYTES.SEC) * CDBL(SECS.CLUST)
  1169.           FREE.DISK.SPACE# = CDBL(FREE.CLUST) * CLUSTER.SIZE#
  1170.           TOTAL.DISK.SPACE# = CDBL(TOTAL.CLUST) * CLUSTER.SIZE#
  1171.           PRINT "There are";FREE.DISK.SPACE#;" bytes free out of";
  1172.           PRINT TOTAL.DISK.SPACE#;" with";CLUSTER.SIZE#;" bytes per cluster"
  1173.  
  1174.  
  1175.  
  1176.  
  1177.  
  1178.  
  1179.  
  1180.  
  1181.  
  1182.  
  1183.  
  1184.  
  1185.  
  1186.  
  1187.  
  1188.  
  1189.  
  1190.  
  1191.  
  1192.  
  1193.  
  1194.  
  1195.  
  1196.      Name: DMPRINT
  1197.  
  1198.      Type: Video / DOS
  1199.  
  1200.      Description:
  1201.           Displays  a string at the current cursor position, using DOS calls
  1202.      for  output  (so  device  drivers  such  as  ANSI.SYS will work).  This
  1203.      routine  is  faster  than  MPRINT  (q.v.),  but offers fewer amenities.
  1204.      Character  translation  is  limited to what DOS provides, meaning that,
  1205.      for  instance,  Backspace  just  moves  the  cursor back without wiping
  1206.      out  the previous character.  Other control codes may not be translated
  1207.      as  you  might  hope,  either.   Finally,  since DOS provides no way of
  1208.      finding  the  current  print position, you have to figure out where the
  1209.      cursor  will  be  yourself if you need it (like other display routines,
  1210.      DMPRINT  does  not  update  the  BASIC  cursor position).  You can gain
  1211.      control  of  such  things  by  using the ANSI.SYS driver.  See your DOS
  1212.      manual for more information on that.
  1213.  
  1214.      Example:
  1215.           CALL DMPRINT(ST$)
  1216.  
  1217.  
  1218.  
  1219.  
  1220.      Name: DOSINKEY
  1221.  
  1222.      Type: Keyboard / DOS
  1223.  
  1224.      Description:
  1225.           Gets  a  key  from  the  standard  input device.  This is normally
  1226.      the  keyboard,  but  redirection  is  allowed  (to a file, or to a port
  1227.      via  CTTY).  Two parameters are returned: the first gives the key code,
  1228.      if  any,  and  the  second gives status information.  If the CHRTYPE is
  1229.      zero,  there  is  no  key  pressed.   If it is one, the key returned is
  1230.      a  normal  keypress.   If  it  is  two, the key returned is the code of
  1231.      an Extended ASCII key (like a function key or arrow key).
  1232.  
  1233.      Example:
  1234.           REM  This is an INKEY$-oriented routine to get a keypress.
  1235.           KY$ = ""
  1236.           WHILE KY$=""
  1237.               KY$ = INKEY$
  1238.           WEND
  1239.           IF LEN(KY$)=2 THEN EXTCODE=-1: KY$=RIGHT$(KY$,1) ELSE EXTCODE=0
  1240.           RETURN
  1241.  
  1242.           REM  This is the same routine, using DOSINKEY.
  1243.           CHRTYPE = 0
  1244.           WHILE CHRTYPE=0
  1245.               CALL DOSINKEY(CHRCODE,CHRTYPE)
  1246.           WEND
  1247.           KY$ = CHR$(CHRCODE)
  1248.           IF CHRTYPE=2 THEN EXTCODE=-1 ELSE EXTCODE=0
  1249.           RETURN
  1250.  
  1251.  
  1252.  
  1253.  
  1254.  
  1255.  
  1256.  
  1257.  
  1258.  
  1259.  
  1260.  
  1261.  
  1262.      Name: DRVSPACE
  1263.  
  1264.      Type: Disk / DOS
  1265.  
  1266.      Description:
  1267.           Returns  the  amount  of  free  space  left on a given disk drive.
  1268.      The  drive  string  may  be  any legal disk drive, or "@" (AT sign) for
  1269.      the default drive, and must be at least one character long.  An illegal
  1270.      drive or other error will cause free space to be returned as a negative
  1271.      value.  See also DISKSTAT.
  1272.  
  1273.      Example:
  1274.           DRV$="A:"
  1275.            .
  1276.            .
  1277.           CALL DRVSPACE(DRV$,A,B,C)
  1278.           FREE# = CDBL(A)*CDBL(B)*CDBL(C)
  1279.           PRINT"Free space on drive ";DRV$;" is";FREE#;"bytes."
  1280.  
  1281.  
  1282.  
  1283.  
  1284.      Name: DTR
  1285.  
  1286.      Type: Miscellaneous / CLONE
  1287.  
  1288.      Description:
  1289.           Switches  the  communications  signal  DTR  (Data  Terminal Ready)
  1290.      on  or  off.   Turning the DTR off has the effect of making most modems
  1291.      drop  carrier  (hang  up  the  phone).   The comm port should be one or
  1292.      two.  Use zero to turn the DTR off, or nonzero to turn it back on.
  1293.  
  1294.      Example:
  1295.           COMMPORT = 1
  1296.           TOGGLE = 0   : REM  turn the DTR off
  1297.           CALL DTR(COMMPORT,TOGGLE)
  1298.  
  1299.  
  1300.  
  1301.  
  1302.      Name: EQUIPMENT
  1303.  
  1304.      Type: Miscellaneous / BIOS
  1305.  
  1306.      Description:
  1307.           Returns  basic  information  about  the  hardware configuration of
  1308.      the  computer: memory  installed,  in  kilobytes;  number  of  parallel
  1309.      (printer)  ports,  0-3;  number  of RS232 serial (comm) ports, 0-7; and
  1310.      number of game ports, 0-1.
  1311.  
  1312.      Example:
  1313.           CALL EQUIPMENT(MEMORY,PARALLEL,SERIAL,GAME)
  1314.  
  1315.  
  1316.  
  1317.  
  1318.  
  1319.  
  1320.  
  1321.  
  1322.  
  1323.  
  1324.  
  1325.  
  1326.  
  1327.  
  1328.      Name: EXIST
  1329.  
  1330.      Type: Disk / DOS
  1331.  
  1332.      Description:
  1333.           Tells  you  if  a  given  file already exists.  Returns zero if it
  1334.      doesn't,  or  a  nonzero  value if it does.  Requires an ASCIZ filename
  1335.      without  wildcards.   If  you  need  to use wildcards, or are operating
  1336.      in a network environment, use the FINDFIRSTF function instead.
  1337.  
  1338.      Example:
  1339.           FIL$ = "TEST.TXT" + CHR$(0)
  1340.           CALL EXIST(FIL$,FILEXISTS)
  1341.           IF FILEXISTS THEN PRINT "File already exists"
  1342.  
  1343.  
  1344.  
  1345.  
  1346.      Name: EXTRACT
  1347.  
  1348.      Type: String / ANY
  1349.  
  1350.      Description:
  1351.           Extracts  a  delimited  substring  from  a  string given an index.
  1352.      Requires  a  string  of  any  length,  a  delimiter of one character in
  1353.      length,  and  an  index value from 1-256; returns the starting location
  1354.      and  length  of  the  substring.   If the delimiter is null (an error),
  1355.      the  substring  length  will  be returned as -1.  If the index value is
  1356.      greater  than  the  number  of  delimited  substrings, a length of zero
  1357.      will be returned.
  1358.  
  1359.      Example:
  1360.           ST$="John Doe/15 Maple Rd/Hometown, CA 99199/(300) 111-1111"
  1361.           INDEX=2
  1362.           DELIMITER$="/"
  1363.           CALL EXTRACT(ST$,DELIMITER$,INDEX,START,SLEN)
  1364.           PRINT MID$(ST$,START,SLEN)
  1365.           REM  This will print the second substring (INDEX=2) of the string
  1366.           REM  (ST$) delimited by "/" (DELIMITER$), which in this case
  1367.           REM  will be "15 Maple Rd".
  1368.  
  1369.  
  1370.  
  1371.  
  1372.  
  1373.  
  1374.  
  1375.  
  1376.  
  1377.  
  1378.  
  1379.  
  1380.  
  1381.  
  1382.  
  1383.  
  1384.  
  1385.  
  1386.  
  1387.  
  1388.  
  1389.  
  1390.  
  1391.  
  1392.  
  1393.  
  1394.      Name: FCLOSE
  1395.  
  1396.      Type: Disk / DOS
  1397.  
  1398.      Description:
  1399.           Closes a file opened by MOPEN (q.v.)
  1400.  
  1401.      Related functions: MCREATE, MOPEN, MREAD, MSETEND, MSETREC, MWRITE.
  1402.  
  1403.      Example:
  1404.           CALL FCLOSE(HANDLE)
  1405.  
  1406.  
  1407.  
  1408.  
  1409.      Name: FCREATE
  1410.  
  1411.      Type: Disk / DOS
  1412.  
  1413.      Description:
  1414.           Opens  a  file  with  a  given  attribute for read/write access in
  1415.      normal  mode.   If  the  file  doesn't exist, it's created; if it does,
  1416.      it's  set  to  zero  bytes in length.  A "handle" is returned, which is
  1417.      used  to  identify  the  file  (like  BASIC's file numbers).  See FOPEN
  1418.      for  an  explanation  of  modes.   For more information, see the end of
  1419.      this manual.
  1420.  
  1421.      Related functions: FOPEN, FREAD, FSETEND, FSETREC, FWRITE.
  1422.  
  1423.      Example:
  1424.           FIL$ = "TEST.TXT" + CHR$(0)
  1425.           ATTR = 0
  1426.           CALL FCREATE(FIL$,ATTR,TEST.HANDLE,ERRCODE)
  1427.           IF ERRCODE THEN PRINT "Couldn't create file"
  1428.  
  1429.  
  1430.  
  1431.  
  1432.  
  1433.  
  1434.  
  1435.  
  1436.  
  1437.  
  1438.  
  1439.  
  1440.  
  1441.  
  1442.  
  1443.  
  1444.  
  1445.  
  1446.  
  1447.  
  1448.  
  1449.  
  1450.  
  1451.  
  1452.  
  1453.  
  1454.  
  1455.  
  1456.  
  1457.  
  1458.  
  1459.  
  1460.      Name: FINDFIRSTF
  1461.  
  1462.      Type: Disk / DOS
  1463.  
  1464.      Description:
  1465.           Given  a  filename  (which  may contain the wildcards "*" and "?",
  1466.      and  a  drive  and  path  spec  if you like), this searches the default
  1467.      (or  specified)  directory  to  find  the first matching file.  Further
  1468.      matches  can  be  obtained  through  the  FINDNEXTF routine (q.v.).  If
  1469.      there  is  a  match,  ERCD  will  return zero, otherwise it will return
  1470.      a  positive  value  (unless  you entered a null filename, in which case
  1471.      ERCD  will  be -1 to flag an error).  You can retrieve various informa-
  1472.      tion  about  the  matched file via a number of supplementary functions:
  1473.      GETNAMEF  to  get  the filename, GETATTRF to get the attribute (there's
  1474.      a  page  at  the end of this document on file attributes), GETDATEF and
  1475.      GETTIMEF  to  get the date and time, and GETSIZEF to get the file size.
  1476.      You  may  specify  a search attribute as well: 0 (zero) to match normal
  1477.      files, 2 to match hidden files, 4 for system files, and 16 for subdirec-
  1478.      tories.   Attributes  other  than zero will return normal files as well
  1479.      as  the  specified  type,  and  you  can match on more than one kind of
  1480.      attribute (for instance, to get all kinds of files, you'd use an attri-
  1481.      bute  of 22, or 2+4+16).  You can read the volume label using an attri-
  1482.      bute  of  8,  which  is  supposed  to return only the volume label, but
  1483.      may not (see notes in the File Attribute info at the end of this file).
  1484.  
  1485.           This  function can be used to duplicate the DOS directory command,
  1486.      or to allow filename wildcards in your program, among other things.
  1487.  
  1488.      Example:
  1489.           FIL$=FIL$+CHR$(0)
  1490.           CALL FINDFIRSTF(FIL$,ATTR,ERCD)
  1491.           IF ERCD THEN PRINT"No matching files"
  1492.  
  1493.  
  1494.  
  1495.  
  1496.  
  1497.  
  1498.  
  1499.  
  1500.  
  1501.  
  1502.  
  1503.  
  1504.  
  1505.  
  1506.  
  1507.  
  1508.  
  1509.  
  1510.  
  1511.  
  1512.  
  1513.  
  1514.  
  1515.  
  1516.  
  1517.  
  1518.  
  1519.  
  1520.  
  1521.  
  1522.  
  1523.  
  1524.  
  1525.  
  1526.      Name: FINDNEXTF
  1527.  
  1528.      Type: Disk / DOS
  1529.  
  1530.      Description:
  1531.           This  is  used  after  the  FINDFIRSTF function (q.v.) in order to
  1532.      find further matching files.
  1533.  
  1534.      Example:
  1535.           CALL FINDNEXTF(ERCD)
  1536.           IF ERCD THEN PRINT"No more matching files"
  1537.  
  1538.  
  1539.  
  1540.  
  1541.  
  1542.  
  1543.  
  1544.  
  1545.  
  1546.  
  1547.  
  1548.  
  1549.  
  1550.  
  1551.  
  1552.  
  1553.  
  1554.  
  1555.  
  1556.  
  1557.  
  1558.  
  1559.  
  1560.  
  1561.  
  1562.  
  1563.  
  1564.  
  1565.  
  1566.  
  1567.  
  1568.  
  1569.  
  1570.  
  1571.  
  1572.  
  1573.  
  1574.  
  1575.  
  1576.  
  1577.  
  1578.  
  1579.  
  1580.  
  1581.  
  1582.  
  1583.  
  1584.  
  1585.  
  1586.  
  1587.  
  1588.  
  1589.  
  1590.  
  1591.  
  1592.      Name: FOPEN
  1593.  
  1594.      Type: Disk / DOS
  1595.  
  1596.      Description:
  1597.           Opens  an  already-existing  file.   If  you  want to create a new
  1598.      file, use the FCREATE function.  You tell it the ASCIZ filename, ACCESS
  1599.      method, and MODE; it gives back a HANDLE or ERRCODE.  The ACCESS method
  1600.      is  how  you  want  to open the file: 0, read; 1, write; 2, read/write.
  1601.      The  MODE  controls  access  to the file by other programs operating at
  1602.      the  same  time,  and is hence only useful for multitasking or network-
  1603.      ing.   MODE is: 0, normal (no multitasking or networking); 1, exclusive
  1604.      (no other program can access the file); 2, deny write (no other program
  1605.      may  change  the  file); 3, deny read (no other program may look at the
  1606.      file);  4, deny none (other programs may access the file).  To activate
  1607.      handling  of  nonzero  modes,  you  must execute the DOS utility SHARE,
  1608.      which  is  included  on  your  DOS disk.  For more information, see the
  1609.      end of this manual.
  1610.  
  1611.      Related functions: FCLOSE, FCREATE, FREAD, FSETEND, FSETREC, FWRITE.
  1612.  
  1613.      Example:
  1614.           FIL$ = "TEST.TXT" + CHR$(0)
  1615.           FACCESS = 2  : REM  Open the file with read/write access
  1616.           FMODE = 0    : REM  Normal mode, not networking or multitasking
  1617.           CALL FOPEN(FIL$,FACCESS,FMODE,TEST.HANDLE,ERRCODE)
  1618.           IF ERRCODE THEN PRINT "Unable to open the file"
  1619.  
  1620.      Example:
  1621.           FIL$ = "C:\DOCUMENT\TEST.TXT" + CHR$(0)
  1622.           FACCESS = 2  : REM  Open the file for read access
  1623.           FMODE = 2    : REM  Deny Write mode, for networking/multitasking
  1624.           REM  We "deny write" so nobody else can change the file while
  1625.           REM
  1626.                we're reading it.  We'll let others read from the file while
  1627.           REM  we are, though.  (This works like Normal mode if SHARE wasn't
  1628.           REM  executed)
  1629.           CALL FOPEN(FIL$,FACCESS,FMODE,TEST.HANDLE,ERRCODE)
  1630.           IF ERRCODE THEN PRINT "Unable to open file"
  1631.  
  1632.  
  1633.  
  1634.  
  1635.  
  1636.  
  1637.  
  1638.  
  1639.  
  1640.  
  1641.  
  1642.  
  1643.  
  1644.  
  1645.  
  1646.  
  1647.  
  1648.  
  1649.  
  1650.  
  1651.  
  1652.  
  1653.  
  1654.  
  1655.  
  1656.  
  1657.  
  1658.  
  1659.      Name: FREAD
  1660.  
  1661.      Type: Disk / DOS
  1662.  
  1663.      Description:
  1664.           Reads  information  from  a  file opened by FOPEN or FCREATE.  You
  1665.      tell  it  which  file  to  read  from by giving it the handle which was
  1666.      returned  when  you  opened  the  file.   You give it a buffer location
  1667.      to read into, which can be either an array (for use, say, with SCRREST)
  1668.      or  a string (for more usual purposes).  You are responsible for seeing
  1669.      that  the  buffer  is  large enough to hold all the bytes that you want
  1670.      to read!
  1671.           FREAD  returns  a  nonzero  ERRCODE  if  anything  went wrong.  If
  1672.      ERRCODE  is -1, it was able to read only part of the information before
  1673.      hitting  an  end  of  file.   In that case, BYTESREAD will tell you how
  1674.      many  bytes  were  actually  read  in.   See the end of this manual for
  1675.      info on error codes.
  1676.  
  1677.      Related functions: FCLOSE, FCREATE, FOPEN, FSETEND, FSETREC, FWRITE
  1678.  
  1679.      Example:
  1680.           OPTION BASE 1 : DIM ARRAY(2000) : REM  Set up the array buffer
  1681.            .
  1682.            .
  1683.           REM  Do a FOPEN to open the file
  1684.           BUFFER = VARPTR(ARRAY(1)) : REM  Use first element of array here
  1685.           BYTES = 4000 : REM  Read in 4000-byte saved screen into the array
  1686.           CALL FREAD(HANDLE,BUFFER,BYTES,BYTESREAD,ERRCODE)
  1687.           IF ERRCODE THEN PRINT "Error reading file..."
  1688.           REM  Do a SCRREST to put the info on the screen
  1689.  
  1690.      Example:
  1691.           BYTES = 128          : REM  Read in 128 bytes/characters
  1692.       
  1693.           BUF$ = SPACE$(BYTES) : REM  Set up the string buffer
  1694.           V = VARPTR(BUF$)
  1695.           BUFFER = PEEK(V+2) + PEEK(V+3) * 256
  1696.           CALL FREAD(HANDLE,BUFFER,BYTES,BYTESREAD,ERRCODE)
  1697.           IF ERRCODE THEN PRINT "Error reading file..."
  1698.  
  1699.  
  1700.  
  1701.  
  1702.  
  1703.  
  1704.  
  1705.  
  1706.  
  1707.  
  1708.  
  1709.  
  1710.  
  1711.  
  1712.  
  1713.  
  1714.  
  1715.  
  1716.  
  1717.  
  1718.  
  1719.  
  1720.  
  1721.  
  1722.  
  1723.  
  1724.  
  1725.  
  1726.      Name: FSETEND
  1727.  
  1728.      Type: Disk / DOS
  1729.  
  1730.      Description:
  1731.           For  use  with  files  opened with FOPEN / FCREATE.  This function
  1732.      sets  the  file pointer to the end of the file, so that any information
  1733.      written using FWRITE will be appended to the file.
  1734.  
  1735.      Related functions: FCLOSE, FCREATE, FOPEN, FREAD, FSETREC, FWRITE
  1736.  
  1737.      Example:
  1738.           CALL FSETEND(HANDLE)
  1739.  
  1740.  
  1741.  
  1742.  
  1743.  
  1744.  
  1745.  
  1746.  
  1747.  
  1748.  
  1749.  
  1750.  
  1751.  
  1752.  
  1753.  
  1754.  
  1755.  
  1756.  
  1757.  
  1758.  
  1759.  
  1760.  
  1761.  
  1762.  
  1763.  
  1764.  
  1765.  
  1766.  
  1767.  
  1768.  
  1769.  
  1770.  
  1771.  
  1772.  
  1773.  
  1774.  
  1775.  
  1776.  
  1777.  
  1778.  
  1779.  
  1780.  
  1781.  
  1782.  
  1783.  
  1784.  
  1785.  
  1786.  
  1787.  
  1788.  
  1789.  
  1790.  
  1791.  
  1792.      Name: FSETREC
  1793.  
  1794.      Type: Disk / DOS
  1795.  
  1796.      Description:
  1797.           For  use  with  files  opened with FOPEN / FCREATE.  This function
  1798.      sets  the  file  pointer to a given record in the file, so that it will
  1799.      be the next record read or written.
  1800.  
  1801.      Related functions: FCLOSE, FCREATE, FOPEN, FREAD, FSETEND, FWRITE
  1802.  
  1803.      Example:
  1804.           RECSIZE = 128 : REM  Number of bytes in a record in our file
  1805.           RECNO = 34    : REM  Record number (starting from 1, as in BASIC)
  1806.           CALL FSETREC(HANDLE,RECSIZE,RECNO)
  1807.  
  1808.  
  1809.  
  1810.  
  1811.      Name: FWRITE
  1812.  
  1813.      Type: Disk / DOS
  1814.  
  1815.      Description:
  1816.           Allows  you  to  write  to a file opened by FOPEN or FCREATE.  The
  1817.      parameters  are  the  same as in FREAD (q.v.), except for BYTESWRITTEN,
  1818.      which replaces BYTESREAD.
  1819.  
  1820.      Related functions: FCLOSE, FCREATE, FOPEN, FREAD, FSETEND, FSETREC
  1821.  
  1822.      Example:
  1823.           REM  Do a SCRSAVE to save a screen into ARRAY()
  1824.           BUFFER = VARPTR(ARRAY(1))
  1825.           BYTES = 4000 : REM  4000 bytes = 2000 integer array elements
  1826.           CALL FWRITE(TEST.HANDLE,BUFFER,BYTES,BYTESWRITTEN,ERRCODE)
  1827.           IF ERRCODE THEN PRINT "Unable to write to file..."
  1828.           REM  See FREAD for an example of how to set up a string buffer
  1829.  
  1830.  
  1831.  
  1832.  
  1833.  
  1834.  
  1835.  
  1836.  
  1837.  
  1838.  
  1839.  
  1840.  
  1841.  
  1842.  
  1843.  
  1844.  
  1845.  
  1846.  
  1847.  
  1848.  
  1849.  
  1850.  
  1851.  
  1852.  
  1853.  
  1854.  
  1855.  
  1856.  
  1857.  
  1858.      Name: GETATTRF
  1859.  
  1860.      Type: Disk / DOS
  1861.  
  1862.      Description:
  1863.           Returns  the  actual  attribute of a file matched using FINDFIRSTF
  1864.      or  FINDNEXTF.   See  the  end of this document for information on file
  1865.      attributes.
  1866.  
  1867.      Example:
  1868.           REM  use this AFTER calling FINDFIRSTF / FINDNEXTF to initialize
  1869.           REM  the appropriate file information!
  1870.           CALL GETATTRF(ATTR)
  1871.  
  1872.  
  1873.  
  1874.  
  1875.      Name: GETCRT
  1876.  
  1877.      Type: Video / BIOS
  1878.  
  1879.      Description:
  1880.           Tells  you what kind of display is being used.  The returned value
  1881.      will be reset if it's monochrome, or set if color.
  1882.  
  1883.      Example:
  1884.           CALL GETCRT(COLORDISPLAY)
  1885.           IF COLORDISPLAY THEN PRINT"Color" ELSE PRINT"Monochrome"
  1886.  
  1887.  
  1888.  
  1889.  
  1890.      Name: GETEXTM
  1891.  
  1892.      Type: Miscellaneous / AT BIOS
  1893.  
  1894.      Description:
  1895.           Tells  you  how  much extended memory is available.  This function
  1896.      requires  the  AT  BIOS,  and  shouldn't  be  used  with PCs.  See also
  1897.      GETLIMM.
  1898.  
  1899.      Example:
  1900.           CALL GETEXTM(KBYTES)
  1901.           PRINT KBYTES;" kilobytes of extended memory"
  1902.  
  1903.  
  1904.  
  1905.  
  1906.  
  1907.  
  1908.  
  1909.  
  1910.  
  1911.  
  1912.  
  1913.  
  1914.  
  1915.  
  1916.  
  1917.  
  1918.  
  1919.  
  1920.  
  1921.  
  1922.  
  1923.  
  1924.      Name: GETKBD
  1925.  
  1926.      Type: Input / CLONE
  1927.  
  1928.      Description:
  1929.           Gives  the  status  of  the  keyboard  toggles.  The variable will
  1930.      be set if the toggle is on, and reset if it is off.  See also SETKBD.
  1931.  
  1932.      Example:
  1933.           CALL GETKBD(INSERT,CAPSLOCK,NUMLOCK,SCROLLLOCK)
  1934.           IF INSERT THEN PRINT"Insert mode is on"
  1935.           IF CAPSLOCK THEN PRINT"Caps Lock is on"
  1936.           IF NUMLOCK THEN PRINT"The keypad is in numeric mode"
  1937.           IF SCROLLLOCK THEN PRINT"Scroll Lock is on"
  1938.  
  1939.  
  1940.  
  1941.  
  1942.      Name: GETDATEF
  1943.  
  1944.      Type: Disk / DOS
  1945.  
  1946.      Description:
  1947.           Returns the date associated with the file matched using FINDFIRSTF
  1948.      or FINDNEXTF.
  1949.  
  1950.      Example:
  1951.           CALL GETDATEF(MONTH,DAY,YEAR)
  1952.  
  1953.  
  1954.  
  1955.  
  1956.      Name: GETDOSV
  1957.  
  1958.      Type: Miscellaneous / DOS
  1959.  
  1960.      Description:
  1961.           Gets  MS-DOS  version.  The major version is returned in the first
  1962.      parameter,  the minor version in the second (e.g., MS-DOS v. 2.11 would
  1963.      return MAJ = 2, MIN = 11).
  1964.  
  1965.      Example:
  1966.           CALL GETDOSV(MAJ,MIN)
  1967.  
  1968.  
  1969.  
  1970.  
  1971.  
  1972.  
  1973.  
  1974.  
  1975.  
  1976.  
  1977.  
  1978.  
  1979.  
  1980.  
  1981.  
  1982.  
  1983.  
  1984.  
  1985.  
  1986.  
  1987.  
  1988.  
  1989.  
  1990.      Name: GETDRV
  1991.  
  1992.      Type: Disk / DOS
  1993.  
  1994.      Description:
  1995.           Returns  the  letter  of the default drive.  The drive string must
  1996.      be at least one character long.
  1997.  
  1998.      Example:
  1999.           DRV$="x:" : CALL GETDRV(DRV$)
  2000.  
  2001.  
  2002.  
  2003.  
  2004.      Name: GETFATTR
  2005.  
  2006.      Type: Disk / DOS
  2007.  
  2008.      Description:
  2009.           Gets  the attribute of a file.  See the section on file attributes
  2010.      at the end of this manual.
  2011.  
  2012.      Example:
  2013.           FIL$ = FIL$ + CHR$(0)
  2014.           CALL GETFATTR(FIL$,ATR)
  2015.  
  2016.  
  2017.  
  2018.  
  2019.      Name: GETFDATE
  2020.  
  2021.      Type: Disk / DOS
  2022.  
  2023.      Description:
  2024.           GETFDATE  returns  the  file  creation date, that is, the date you
  2025.      see  on  a  file  when  you  get  a  DIRectory.   The file name must be
  2026.      terminated  with  a NUL character.  If there is an error, such as there
  2027.      being no such file, the month will be set to -1.
  2028.  
  2029.      Example:
  2030.           FIL$ = "TESTFILE.TXT" + CHR$(0)
  2031.           CALL GETFDATE(FIL$,MONTH,DAY,YEAR)
  2032.  
  2033.  
  2034.  
  2035.  
  2036.  
  2037.  
  2038.  
  2039.  
  2040.  
  2041.  
  2042.  
  2043.  
  2044.  
  2045.  
  2046.  
  2047.  
  2048.  
  2049.  
  2050.  
  2051.  
  2052.  
  2053.  
  2054.  
  2055.  
  2056.      Name: GETFTIME
  2057.  
  2058.      Type: Disk / DOS
  2059.  
  2060.      Description:
  2061.           This  function complements GETFDATE, and returns the file creation
  2062.      time.   The  hour is in 24-hour (military) format, and will be returned
  2063.      as  -1  if  there  is no such file or a bad file name.  The seconds are
  2064.      rounded  to  the next lower even number, due to the DOS storage format.
  2065.      The file name must be terminated with a NUL character.
  2066.  
  2067.      Example:
  2068.           FIL$ = "ANYFILE.EXT" + CHR$(0)
  2069.           CALL GETFTIME(FIL$,HOUR,MINUTE,SECOND)
  2070.  
  2071.  
  2072.  
  2073.  
  2074.      Name: GETKEY
  2075.  
  2076.      Type: Keyboard / BIOS
  2077.  
  2078.      Description:
  2079.           Waits  until  one  of  a  list of keys is pressed, and returns it.
  2080.      The  key  list  (any  length)  should be uppercase.  If the key list is
  2081.      null,  the  first  key pressed will be returned.  The key returned will
  2082.      be  capitalized.   The  variable  to return the key in must be at least
  2083.      one  character  long.   This  function is designed for returning one of
  2084.      a menu of choices, for example.
  2085.  
  2086.      Example:
  2087.           PRINT "Would you like to try again (Y/N)? ";
  2088.           GOODKEYS$="YN" : REM  Allow Y or N
  2089.             .
  2090.             .
  2091.           KY$="x": CALL GETKEY(GOODKEYS$,KY$)
  2092.  
  2093.  
  2094.  
  2095.  
  2096.      Name: GETLIMM
  2097.  
  2098.      Type: Miscellaneous / BIOS
  2099.  
  2100.      Description:
  2101.           Returns  the  status  of  expanded memory, in total pages and free
  2102.      pages  (where  a  page  is  16k  bytes).   Total  pages will be zero if
  2103.      expanded  memory  is not installed, or if the LIM driver is not active.
  2104.      See also GETEXTM.
  2105.  
  2106.      Example:
  2107.           CALL GETLIMM(TOTPAGES,FREEPAGES)
  2108.           PRINT TOTPAGES;"pages of LIM memory are installed."
  2109.           IF TOTPAGES>0 THEN PRINT FREEPAGES;"pages of that are free."
  2110.  
  2111.  
  2112.  
  2113.  
  2114.  
  2115.  
  2116.  
  2117.  
  2118.  
  2119.  
  2120.  
  2121.  
  2122.      Name: GETLINE
  2123.  
  2124.      Type: Video / ANY
  2125.  
  2126.      Description:
  2127.           Returns  a  selected  line  from  a screen saved via SCRSAVE, with
  2128.      the  trailing  spaces  removed.   The  line  string must be at least 80
  2129.      characters long.
  2130.  
  2131.      Example:
  2132.           DEFINT A-Z: OPTION BASE 1: DIM SCR(2000)
  2133.           WHERE=VARPTR(SCR(1)): CALL SCRSAVE(WHERE): CLS
  2134.           LINENR=10: LIN$=SPACE$(80): WHERE=VARPTR(SCR(1))
  2135.           CALL GETLINE(WHERE,LINENR,LIN$,LLEN)
  2136.           PRINT"Line 10 was:": PRINT LEFT$(LIN$,LLEN)
  2137.  
  2138.  
  2139.  
  2140.  
  2141.      Name: GETNAMEF
  2142.  
  2143.      Type: Disk / DOS
  2144.  
  2145.      Description:
  2146.           Returns  the  filename  of  the  file  matched using FINDFIRSTF or
  2147.      FINDNEXTF.   The FIL$ string must be initialized to at least 12 charac-
  2148.      ters  in  length.   The actual length of FIL$ will be returned in FLEN,
  2149.      which  will  be  -1  if  you  didn't initialize FIL$ long enough.  Note
  2150.      that the filename will not contain a drive or path spec.
  2151.  
  2152.      Example:
  2153.           FIL$ = SPACE$(12)
  2154.           CALL GETNAMEF(FIL$,FLEN)
  2155.           FIL$ = LEFT$(FIL$,FLEN)
  2156.  
  2157.  
  2158.  
  2159.  
  2160.  
  2161.  
  2162.  
  2163.  
  2164.  
  2165.  
  2166.  
  2167.  
  2168.  
  2169.  
  2170.  
  2171.  
  2172.  
  2173.  
  2174.  
  2175.  
  2176.  
  2177.  
  2178.  
  2179.  
  2180.  
  2181.  
  2182.  
  2183.  
  2184.  
  2185.  
  2186.  
  2187.  
  2188.      Name: GETSCREEN
  2189.  
  2190.      Type: Video / CLONE
  2191.  
  2192.      Description:
  2193.           Allows  you  to  save  any  part  of a text screen display (on any
  2194.      page,  active  or  inactive,  if  you  have  a color graphics adapter).
  2195.      You  need  to  specify  an  integer array where the information will be
  2196.      stored,  the  coordinates  of  the  upper  left corner and bottom right
  2197.      corner  of  the  part  of the screen to save, the display page to save,
  2198.      and the screen mode.
  2199.           The  screen  mode  should  be  zero for flicker-free screen saving
  2200.      if  you  have  a  low quality color graphics adapter and are saving the
  2201.      currently-active  display  page.   Otherwise, set it to 1 or -1 for the
  2202.      fastest save speed.
  2203.           You  specify  the  area  of  the screen to save as a rectangle, by
  2204.      giving  the  locations of the upper leftmost corner and lower rightmost
  2205.      corner  of  the  area  to save.  This can range from a single character
  2206.      to  the entire screen.  Make sure that the coordinates do not get mixed
  2207.      up, or you will get unpredictable results.
  2208.           To  figure  out  how  many array elements you need to save an area
  2209.      of the screen, use the following calculation:
  2210.      ELEMENTS = (BOTTOMROW - TOPROW +1) * (RIGHTCOLUMN - LEFTCOLUMN +1)
  2211.      You  can  store  multiple  screen  areas in one array by specifying the
  2212.      proper  starting  element,  which  must be one after the previous saved
  2213.      area.   You'll  have  to  keep track of where each saved area is in the
  2214.      array yourself.
  2215.           If you have a monochrome adapter, or are not using unusual display
  2216.      pages, you should set the page specification to zero.
  2217.           Note  that  you don't have to restore the saved area of the screen
  2218.      (see  PUTSCREEN)  to  the same area it was taken from.  This allows you
  2219.      to move windows around, change the shape of windows, and other interes-
  2220.      ting tricks...
  2221.           See  also  PUTSCREEN,  to  restore a given area of the screen; and
  2222.      SCRSAVE, SCRREST, SCRSAVEP, SCRRESTP, SCRSAVEPD, and SCRRESTPD, earlier
  2223.      versions  of  similar  functions.  Note that if you save/restore a full
  2224.      80-column,  25-row  screen,  the  information in the save/restore array
  2225.      is    identical    whether    you're   using   GETSCREEN/PUTSCREEN   or
  2226.      SCRSAVExx/SCRRESTxx.   On  that  level,  the  routines  are  completely
  2227.      compatible.
  2228.  
  2229.      Example:
  2230.           CALL GETSCREEN(SCRN(0),TOPROW,LFTCOL,BOTROW,RGTCOL,PAGE,SCRNMODE)
  2231.           REM  SCRN(0) is the location in the array to save the area to.
  2232.           REM  TOPROW,LFTCOL and BOTROW,RGTCOL are the corners of the area.
  2233.           REM  PAGE is the display page number (0-3 if Color, 0 if Mono).
  2234.           REM
  2235.                SCRNMODE is screen access mode: 0, snowless; 1 / -1, fast.
  2236.  
  2237.  
  2238.  
  2239.  
  2240.  
  2241.  
  2242.  
  2243.  
  2244.  
  2245.  
  2246.  
  2247.  
  2248.  
  2249.  
  2250.  
  2251.  
  2252.  
  2253.  
  2254.  
  2255.      Name: GETSIZEF
  2256.  
  2257.      Type: Disk / DOS
  2258.  
  2259.      Description:
  2260.           Returns  the size of the file matched via FINDFIRSTF or FINDNEXTF.
  2261.      Since  the  file  size  may  be  outside  integer bounds, there is some
  2262.      additional code you will have to add which uses double-precision values
  2263.      (see  the example).  You can modify the example to use single-precision
  2264.      instead,  but  really large file sizes will then lapse into exponential
  2265.      notation.
  2266.  
  2267.      Example:
  2268.           CALL GETSIZEF(SIZELOW,SIZEHIGH): SIZELOW# = CDBL(SIZELOW)
  2269.           IF SIZELOW < 0 THEN SIZELOW# = SIZELOW# + 65536#
  2270.           FILESIZE# = SIZELOW# + CDBL(SIZEHIGH) * 65536#
  2271.  
  2272.  
  2273.  
  2274.  
  2275.      Name: GETSUB
  2276.  
  2277.      Type: Disk / DOS
  2278.  
  2279.      Description:
  2280.           Gets  the  default  subdirectory.   The  subdirectory  string must
  2281.      be  64  characters  long,  and it is recommended that you set it to NUL
  2282.      characters.   Note  that  the  returned  string  will NOT be started by
  2283.      a backslash "\" character-- you should add one if appropriate.
  2284.  
  2285.      Example:
  2286.           SUB$ = STRING$(64,0): CALL GETSUB(SUB$,SLEN)
  2287.           SUB$ = "\" + LEFT$(SUB$,SLEN)
  2288.  
  2289.  
  2290.  
  2291.  
  2292.      Name: GETTIMEF
  2293.  
  2294.      Type: Disk / DOS
  2295.  
  2296.      Description:
  2297.           Returns  the  time  associated with the file matched by FINDFIRSTF
  2298.      or FINDNEXTF.  The hour is returned in military (24-hour) format.
  2299.  
  2300.      Example:
  2301.           CALL GETTIMEF(HOUR,MINUTE,SECOND)
  2302.  
  2303.  
  2304.  
  2305.  
  2306.  
  2307.  
  2308.  
  2309.  
  2310.  
  2311.  
  2312.  
  2313.  
  2314.  
  2315.  
  2316.  
  2317.  
  2318.  
  2319.  
  2320.  
  2321.      Name: INSCHR
  2322.  
  2323.      Type: Video / CLONE
  2324.  
  2325.      Description:
  2326.           Inserts  a  space at the specified screen location.  The character
  2327.      previously  at  that  position  and  all  characters to the right of it
  2328.      on  the  same  screen  line  will  be shifted right one space.  Subject
  2329.      to the same limitations as DELCHR (q.v.).
  2330.  
  2331.      Example:
  2332.           COL = POS(0): ROW = CSRLIN
  2333.           CALL INSCHR(ROW,COL): PRINT"*";
  2334.  
  2335.  
  2336.  
  2337.  
  2338.      Name: INT2DATE
  2339.  
  2340.      Type: Miscellaneous / ANY
  2341.  
  2342.      Description:
  2343.           Decompresses  a  date  squeezed  using  DATE2INT (q.v.).  The year
  2344.      will be a four-digit value (1900-2026).
  2345.  
  2346.      Example:
  2347.           CALL INT2DATE(MONTH,DAY,YEAR,SQZDATE)
  2348.  
  2349.  
  2350.  
  2351.  
  2352.      Name: INT2TIME
  2353.  
  2354.      Type: Miscellaneous / ANY
  2355.  
  2356.      Description:
  2357.           Decompresses  a  time squeezed using TIME2INT (q.v.).  The seconds
  2358.      will be an even value (rounded down) due to the storage format.
  2359.  
  2360.      Example:
  2361.           CALL INT2TIME(HOUR,MIN,SEC,SQZTIME)
  2362.  
  2363.  
  2364.  
  2365.  
  2366.  
  2367.  
  2368.  
  2369.  
  2370.  
  2371.  
  2372.  
  2373.  
  2374.  
  2375.  
  2376.  
  2377.  
  2378.  
  2379.  
  2380.  
  2381.  
  2382.  
  2383.  
  2384.  
  2385.  
  2386.  
  2387.      Name: KEYPRESS
  2388.  
  2389.      Type: Keyboard / BIOS
  2390.  
  2391.      Description:
  2392.           Tells  you  whether  a  key is waiting in the keyboard buffer (for
  2393.      use  with  INKEY$  routines,  etc).   KYHIT is set if a key is waiting,
  2394.      cleared otherwise.
  2395.  
  2396.      Example:
  2397.           100 CALL KEYPRESS(KYHIT)
  2398.               IF KYHIT THEN KY$=INKEY$ ELSE 100
  2399.  
  2400.  
  2401.  
  2402.  
  2403.      Name: LOCASE
  2404.  
  2405.      Type: String / ANY
  2406.  
  2407.      Description:
  2408.           Converts a string to all lowercase characters.
  2409.  
  2410.      Example:
  2411.           MSG$="THis IS a test OF tHe lowercase CONVERTER!"
  2412.             .
  2413.             .
  2414.           CALL LOCASE(MSG$)
  2415.  
  2416.  
  2417.  
  2418.  
  2419.  
  2420.  
  2421.  
  2422.  
  2423.  
  2424.  
  2425.  
  2426.  
  2427.  
  2428.  
  2429.  
  2430.  
  2431.  
  2432.  
  2433.  
  2434.  
  2435.  
  2436.  
  2437.  
  2438.  
  2439.  
  2440.  
  2441.  
  2442.  
  2443.  
  2444.  
  2445.  
  2446.  
  2447.  
  2448.  
  2449.  
  2450.  
  2451.  
  2452.  
  2453.      Name: LROTATE
  2454.  
  2455.      Type: String / ANY
  2456.  
  2457.      Description:
  2458.           Rotates  the  characters  in a string left.  That is, the leftmost
  2459.      character  is  removed,  and  tacked  onto the end of the string.  This
  2460.      is  useful  for  rotating  queues and for character-graphics animation.
  2461.      If the string is of length one or less, it is returned unchanged.
  2462.  
  2463.      Example:
  2464.           ST$ = "12345": CALL LROTATE(ST$)
  2465.           REM  ST$ will end up being "23451"
  2466.  
  2467.  
  2468.  
  2469.  
  2470.      Name: MAKESUB
  2471.  
  2472.      Type: Disk / DOS
  2473.  
  2474.      Description:
  2475.           Makes  a  subdirectory.   Use  a  NUL-terminated string to specify
  2476.      the  subdirectory.   An  error  code  will  be returned if there was an
  2477.      error.
  2478.  
  2479.      Example:
  2480.           TMP$ = SUB$+CHR$(0): CALL MAKESUB(TMP$,ERRCODE)
  2481.           IF ERRCODE THEN couldn't make subdir ELSE subdir created
  2482.  
  2483.  
  2484.  
  2485.  
  2486.  
  2487.  
  2488.  
  2489.  
  2490.  
  2491.  
  2492.  
  2493.  
  2494.  
  2495.  
  2496.  
  2497.  
  2498.  
  2499.  
  2500.  
  2501.  
  2502.  
  2503.  
  2504.  
  2505.  
  2506.  
  2507.  
  2508.  
  2509.  
  2510.  
  2511.  
  2512.  
  2513.  
  2514.  
  2515.  
  2516.  
  2517.  
  2518.  
  2519.      Name: MAKEWINDOW
  2520.  
  2521.      Type: Video / CLONE
  2522.  
  2523.      Description:
  2524.           Creates  a  pop-up  window  on the screen.  You specify the window
  2525.      by  giving  the  upper left corner and lower right corner of the inside
  2526.      of  the  window.   The  frame  is  drawn  -outside-  the  window you've
  2527.      specified, so be sure to allow room for the frame!  For normal windows,
  2528.      the  frame  takes up only one column or row on each side.  For shadowed
  2529.      windows,  the  frame  will  instead  take  up three columns on the left
  2530.      and three rows on the bottom.
  2531.  
  2532.           There are four types of window:
  2533.      0, Normal:   the window pops onto the screen.
  2534.      1, Growing:  the window "grows" from a spot to a full-sized window.
  2535.      2,  Shadowed:  the  window  is shadowed on the left and bottom for a 3D
  2536.         effect.
  2537.      3, Growing/Shadowed: the window is shadowed and grows.
  2538.  
  2539.           You may also choose five types of frames:
  2540.      0, None: composed of spaces.
  2541.      1, Single: composed of a single line.
  2542.      2, Double: composed of a double line.
  2543.      3,  Double/Single:  made with a double vertical and a single horizontal
  2544.         line.
  2545.      4,  Single/Double:  made with a single vertical and a double horizontal
  2546.         line.
  2547.  
  2548.           You  must select fore and background colors.  A label is optional.
  2549.      If  you  give  one, it is bracketed within the top of the frame, on the
  2550.      left side.  The screen page is selectable on color monitors.
  2551.  
  2552.      Example:
  2553.           LCOL=5:  TROW=5:  REM  top left corner
  2554.           RCOL=79: BROW=20: REM  bottom right corner
  2555.           LABEL$="Test Window"
  2556.           FORE=7: BACK=0:   REM  color/attributes
  2557.           PAGE=0:           REM  screen display page
  2558.           FRAME=1:          REM  single-line frame
  2559.           TYPE=3:           REM  growing, shadowed window
  2560.        CALL MAKEWINDOW(LCOL,TROW,RCOL,BROW,LABEL$,FRAME,TYPE,FORE,BACK,PAGE)
  2561.  
  2562.  
  2563.  
  2564.  
  2565.  
  2566.  
  2567.  
  2568.  
  2569.  
  2570.  
  2571.  
  2572.  
  2573.  
  2574.  
  2575.  
  2576.  
  2577.  
  2578.  
  2579.  
  2580.  
  2581.  
  2582.  
  2583.  
  2584.  
  2585.      Name: MDELCHR
  2586.  
  2587.      Type: Video / BIOS
  2588.  
  2589.      Description:
  2590.           Deletes  the  character  at the current cursor position.  It obeys
  2591.      the  window  defined  by  MWINDOW.   It's  more compatible than DELCHR,
  2592.      but much slower.
  2593.             Note  that  this  routine  can  be  used to scroll a window left
  2594.      by  doing an MDELCHR at the first location of each line to be scrolled.
  2595.      To scroll right, do the same using MINSCHR instead.
  2596.  
  2597.      Example:
  2598.           CALL MDELCHR
  2599.  
  2600.  
  2601.  
  2602.  
  2603.      Name: MINSCHR
  2604.  
  2605.      Type: Video / BIOS
  2606.  
  2607.      Description:
  2608.           Inserts a space at the current cursor position, obeying the window
  2609.      defined by MWINDOW.  See notes at MDELCHR.
  2610.  
  2611.      Example:
  2612.           CALL MINSCHR
  2613.  
  2614.  
  2615.  
  2616.  
  2617.  
  2618.  
  2619.  
  2620.  
  2621.  
  2622.  
  2623.  
  2624.  
  2625.  
  2626.  
  2627.  
  2628.  
  2629.  
  2630.  
  2631.  
  2632.  
  2633.  
  2634.  
  2635.  
  2636.  
  2637.  
  2638.  
  2639.  
  2640.  
  2641.  
  2642.  
  2643.  
  2644.  
  2645.  
  2646.  
  2647.  
  2648.  
  2649.  
  2650.  
  2651.      Name: MMBUTTON
  2652.  
  2653.      Type: Input / BIOS
  2654.  
  2655.      Description:
  2656.           Returns  which  mouse  buttons are currently being held down.  See
  2657.      also MMCLICK.
  2658.  
  2659.      Example:
  2660.           CALL MMBUTTON(LFT,RGT)
  2661.           IF LFT THEN PRINT "The left button is being pressed."
  2662.           IF RGT THEN PRINT "The right button is being pressed."
  2663.  
  2664.  
  2665.  
  2666.  
  2667.      Name: MMCHECK
  2668.  
  2669.      Type: Input / BIOS
  2670.  
  2671.      Description:
  2672.           Returns  whether  a  mouse  is  installed, and how many buttons it
  2673.      has if it is installed.
  2674.  
  2675.      Example:
  2676.           CALL MMCHECK(MOUSE)
  2677.           IF MOUSE THEN PRINT "A mouse with ";MOUSE;" buttons is installed."
  2678.  
  2679.  
  2680.  
  2681.  
  2682.      Name: MMCLICK
  2683.  
  2684.      Type: Input / BIOS
  2685.  
  2686.      Description:
  2687.           Returns  which  mouse  buttons  have  been  clicked since you last
  2688.      used this function.  See also MMBUTTON.
  2689.  
  2690.      Example:
  2691.           CALL MMCLICK(LFT,RGT)
  2692.           IF LFT THEN PRINT "The left button was pressed."
  2693.           IF RGT THEN PRINT "The right button was pressed."
  2694.  
  2695.  
  2696.  
  2697.  
  2698.  
  2699.  
  2700.  
  2701.  
  2702.  
  2703.  
  2704.  
  2705.  
  2706.  
  2707.  
  2708.  
  2709.  
  2710.  
  2711.  
  2712.  
  2713.  
  2714.  
  2715.  
  2716.  
  2717.      Name: MMCURSORON
  2718.  
  2719.      Type: Input / BIOS
  2720.  
  2721.      Description:
  2722.           Makes  the  cursor  associated  with  the  mouse visible.  This is
  2723.      normally  a  blinking  block,  and  shows  where the mouse is currently
  2724.      pointing.  See also MMCURSOROFF.
  2725.  
  2726.      Example:
  2727.           CALL MMCURSORON
  2728.  
  2729.  
  2730.  
  2731.      Name: MMCURSOROFF
  2732.  
  2733.      Type: Input / BIOS
  2734.  
  2735.      Description:
  2736.           Makes  the  cursor  associated with the mouse invisible.  See also
  2737.      MMCURSORON.
  2738.  
  2739.      Example:
  2740.           CALL MMCURSOROFF.
  2741.  
  2742.  
  2743.  
  2744.  
  2745.      Name: MMGETLOC
  2746.  
  2747.      Type: Input / BIOS
  2748.  
  2749.      Description:
  2750.           Gets  the  current location of the mouse cursor.  This is returned
  2751.      as  a  value  from  0-639 for columns, and 0-199 for rows.  You need to
  2752.      adjust  this  for  the  current screen format.  If you're in text mode,
  2753.      divide  the  columns  by eight and the rows by eight.  If you're in low
  2754.      res  graphics  mode,  divide the columns by two.  If you're in high res
  2755.      graphics, the numbers are fine.
  2756.  
  2757.      Example:
  2758.           CALL MMGETLOC(COL,ROW)
  2759.           LOCATE ROW,COL: PRINT "!";
  2760.  
  2761.  
  2762.  
  2763.  
  2764.  
  2765.  
  2766.  
  2767.  
  2768.  
  2769.  
  2770.  
  2771.  
  2772.  
  2773.  
  2774.  
  2775.  
  2776.  
  2777.  
  2778.  
  2779.  
  2780.  
  2781.  
  2782.  
  2783.      Name: MMSETLOC
  2784.  
  2785.      Type: Input / BIOS
  2786.  
  2787.      Description:
  2788.           Sets  the current value of the mouse cursor.  Uses the same format
  2789.      as MMGETLOC (q.v.).
  2790.  
  2791.      Example:
  2792.           COL=40*8-8: ROW=24*8-8: REM  middle of the text-mode screen
  2793.           CALL MMSETLOC(COL,ROW)
  2794.  
  2795.  
  2796.  
  2797.  
  2798.      Name: MMSETRANGE
  2799.  
  2800.      Type: Input / BIOS
  2801.  
  2802.      Description:
  2803.           Sets  the  range  of  locations  where the mouse cursor is allowed
  2804.      to  be.   This  is  done  by specifying the upper left corner and lower
  2805.      right  corner  of  the  edges  of  the mouse input field.  Use the same
  2806.      format as MMGETLOC (q.v.).
  2807.  
  2808.      Example:
  2809.           LFTCOL=20*8-8: TOPROW=1*8-8
  2810.           RGTCOL=60*8-8: BOTROW=10*8-8
  2811.           CALL MMSETRANGE(LFTCOL,TOPROW,RGTCOL,BOTROW)
  2812.           REM  sets up a text-mode input field
  2813.  
  2814.  
  2815.  
  2816.  
  2817.  
  2818.  
  2819.  
  2820.  
  2821.  
  2822.  
  2823.  
  2824.  
  2825.  
  2826.  
  2827.  
  2828.  
  2829.  
  2830.  
  2831.  
  2832.  
  2833.  
  2834.  
  2835.  
  2836.  
  2837.  
  2838.  
  2839.  
  2840.  
  2841.  
  2842.  
  2843.  
  2844.  
  2845.  
  2846.  
  2847.  
  2848.  
  2849.      Name: MLOAD
  2850.  
  2851.      Type: Disk / DOS
  2852.  
  2853.      Description:
  2854.           Works  the  same  way  as  the  BLOAD statement does.  This is for
  2855.      use  with  older compilers, which don't have the BLOAD statement imple-
  2856.      mented.   MLOAD  restores the information to the same place it was when
  2857.      BSAVEd.
  2858.  
  2859.      Example:
  2860.           FIL$ = "SCRNSAVE.BIN" + CHR$(0)
  2861.           CALL MLOAD(FIL$)
  2862.  
  2863.  
  2864.  
  2865.  
  2866.      Name: MONTH
  2867.  
  2868.      Type: Miscellaneous / ANY
  2869.  
  2870.      Description:
  2871.           Given  the  number  of  a  month  (1-12), this routine returns the
  2872.      name  of  the  month  (January  -  December).  You must supply a string
  2873.      of at least nine spaces in length to hold the month.
  2874.  
  2875.      Example:
  2876.           MONTH$ = SPACE$(9)
  2877.           CALL MONTH(MONTH$,MLENGTH,MONTHNUMBER)
  2878.           MONTH$ = LEFT$(MONTH$,MLENGTH)
  2879.  
  2880.  
  2881.  
  2882.  
  2883.  
  2884.  
  2885.  
  2886.  
  2887.  
  2888.  
  2889.  
  2890.  
  2891.  
  2892.  
  2893.  
  2894.  
  2895.  
  2896.  
  2897.  
  2898.  
  2899.  
  2900.  
  2901.  
  2902.  
  2903.  
  2904.  
  2905.  
  2906.  
  2907.  
  2908.  
  2909.  
  2910.  
  2911.  
  2912.  
  2913.  
  2914.  
  2915.      Name: MPRINTC
  2916.  
  2917.      Type: Video / BIOS
  2918.  
  2919.      Description:
  2920.           Using  this  function,  you  can  access  device  drivers  such as
  2921.      ANSI.SYS.   This  is  a video output function which goes through MS-DOS
  2922.      function   calls.   It  prints  a  single  character  to  the  display.
  2923.      MPRINTC allows use of ANSI.SYS and similar video drivers, and windowing
  2924.      via  MWINDOW,  but is slower and takes more memory that the usual PRINT
  2925.      statement.
  2926.  
  2927.      Example:
  2928.           CALL MPRINTC(CH$,COL,ROW): LOCATE ROW,COL
  2929.  
  2930.  
  2931.  
  2932.  
  2933.      Name: MPRINT
  2934.  
  2935.      Type: Video / BIOS
  2936.  
  2937.      Description:
  2938.           Same  as  MPRINTC  (q.v.),  only  it  allows you to send an entire
  2939.      string out to the display, rather than just a single character.
  2940.  
  2941.      Example:
  2942.           CALL MPRINT(ST$,COL,ROW): LOCATE ROW,COL
  2943.  
  2944.  
  2945.  
  2946.  
  2947.  
  2948.  
  2949.  
  2950.  
  2951.  
  2952.  
  2953.  
  2954.  
  2955.  
  2956.  
  2957.  
  2958.  
  2959.  
  2960.  
  2961.  
  2962.  
  2963.  
  2964.  
  2965.  
  2966.  
  2967.  
  2968.  
  2969.  
  2970.  
  2971.  
  2972.  
  2973.  
  2974.  
  2975.  
  2976.  
  2977.  
  2978.  
  2979.  
  2980.  
  2981.      Name: MULTIAND
  2982.  
  2983.      Type: String / ANY
  2984.  
  2985.      Description:
  2986.           This is a flexible function with many possible uses.  Every charac-
  2987.      ter  in  a  given  string  is ANDed with a value you supply.  One thing
  2988.      this  could  be  used for is translating Wordstar files to ASCII files,
  2989.      by  using  a bit mask (the value that will be ANDed with the character)
  2990.      of  &H7F,  which strips off the high bit of each character.  The string
  2991.      may  be  any length; the bit mask is an integer, with only the low byte
  2992.      in use (value of 0-255).
  2993.  
  2994.      Example:
  2995.           ST$ = "" : FOR X=65 TO 70: ST$ = CHR$(X)+CHR$(X+128): NEXT
  2996.           PRINT ST$
  2997.           BITMASK = &H7F : CALL MULTIAND(ST$,BITMASK)
  2998.           PRINT ST$
  2999.  
  3000.  
  3001.  
  3002.  
  3003.      Name: MULTIOR
  3004.  
  3005.      Type: String / ANY
  3006.  
  3007.      Description:
  3008.           Does  the  exact  opposite  of MULTIAND-- instead of stripping off
  3009.      bits,  it  turns  on  bits.   It ORs instead of ANDs.  One possible use
  3010.      for  this would be to encode a text string by ORing with 128, and later
  3011.      decoding  by  ANDing with 128.  This would allow you to save the string
  3012.      to  disk  using  text files, even if the string included control codes,
  3013.      although  that  won't  work right if the string has graphics characters
  3014.      (using  ExtASCII codes, which are codes from 128-255) in it.  The para-
  3015.      meters are the same as for MULTIAND.
  3016.  
  3017.      Example:
  3018.           ST$ = "ABCDE": PRINT ST$: SETBITS = &H80
  3019.           CALL MULTIOR(ST$,SETBITS): PRINT ST$
  3020.  
  3021.  
  3022.  
  3023.  
  3024.  
  3025.  
  3026.  
  3027.  
  3028.  
  3029.  
  3030.  
  3031.  
  3032.  
  3033.  
  3034.  
  3035.  
  3036.  
  3037.  
  3038.  
  3039.  
  3040.  
  3041.  
  3042.  
  3043.  
  3044.  
  3045.  
  3046.  
  3047.      Name: MULTIXOR
  3048.  
  3049.      Type: String / ANY
  3050.  
  3051.      Description:
  3052.           An  exclusive-or  operation  for strings.  Bits in the string will
  3053.      be  set  only  if they are set in the string byte or mask byte, but not
  3054.      in  both  of them.  Note that this can be used as a "MULTINOT" function
  3055.      by  using  a  mask  of  &HFF or 255.  In this case, all bits are set in
  3056.      the  mask, so the result of the XOR will be the same as a NOT operation
  3057.      on  the  string.   Note  that XORing a string with the same value twice
  3058.      will  return  the  original  string-- it can thus be used to encode and
  3059.      decode strings.
  3060.  
  3061.      Example:
  3062.           CALL MULTIXOR(ST$,MASK)
  3063.  
  3064.  
  3065.  
  3066.  
  3067.      Name: MWINDOW
  3068.  
  3069.      Type: Video / BIOS
  3070.  
  3071.      Description:
  3072.           Sets  up  a  window  for the MPRINT and MPRINTC routines.  Windows
  3073.      are  defined  by  their  upper left corner and lower right corner.  The
  3074.      default  window  is  thus (1,1,80,24), which leaves out the bottom line
  3075.      (BASIC's  status  line).   To  use  the  full screen, call this routine
  3076.      with  values  (1,1,80,25).   Note  that the cursor should be positioned
  3077.      inside the window before using MPRINT/MPRINTC.
  3078.      Note also that windows should be defined to contain at least two rows.
  3079.  
  3080.      Example:
  3081.           LFTCOL = 20: TOPROW = 5: RTCOL = 60: BOTROW = 15
  3082.           CALL MWINDOW(LFTCOL,TOPROW,RTCOL,BOTROW): LOCATE TOPROW,LFTCOL
  3083.           REM  sets up a window (of 40 cols x 10 rows)
  3084.           REM  in the middle of the screen.
  3085.  
  3086.  
  3087.  
  3088.  
  3089.  
  3090.  
  3091.  
  3092.  
  3093.  
  3094.  
  3095.  
  3096.  
  3097.  
  3098.  
  3099.  
  3100.  
  3101.  
  3102.  
  3103.  
  3104.  
  3105.  
  3106.  
  3107.  
  3108.  
  3109.  
  3110.  
  3111.  
  3112.  
  3113.      Name: PRINTSCREEN
  3114.  
  3115.      Type: Miscellaneous / BIOS
  3116.  
  3117.      Description:
  3118.           This  sends  an  image  of  the  current screen display out to the
  3119.      first  printer  device.   It  works  exactly in the same way as doing a
  3120.      Shift-PrtSc  from  the  keyboard,  so  it  can display graphics as well
  3121.      as text if you have the DOS GRAPHICS program installed.
  3122.  
  3123.  
  3124.  
  3125.  
  3126.      Name: PUTSCREEN
  3127.  
  3128.      Type: Video / CLONE
  3129.  
  3130.      Description:
  3131.           This  restores  an  area  of  the  screen that was saved using the
  3132.      GETSCREEN  function  (q.v.).   You need not restore an area to the same
  3133.      screen coordinates or to the same display page.
  3134.           It  is  possible  to  change  the shape of an area by changing the
  3135.      coordinates  specified.   For  instance,  suppose  you  had saved a six
  3136.      character,  one  line  message,  "FOOBAR",  at coordinates (1,1)-(1,6).
  3137.      You  could  restore it as a three char by two line message, "FOO" "BAR"
  3138.      by specifying the coordinates (1,1)-(2,3).  Note that these coordinates
  3139.      are  in Microsoft's mixed up form of (ROW,COLUMN), not the normal alge-
  3140.      braic format.
  3141.           It  is  also  possible to restore only part of the screen that was
  3142.      saved.   For  instance,  suppose  you had saved the entire screen in an
  3143.      array SCRN starting at element 0, and only wanted to restore the bottom
  3144.      half  of  the  screen.  Using the calculation for screen elements given
  3145.      in  GETSCREEN,  you  would  find that 2000 elements were needed for the
  3146.      whole  screen, or only 1000 elements for the bottom half of the screen.
  3147.      That  means  that  in  the  array,  elements 0-999 hold the top half of
  3148.      the  screen,  and  1000-1999  hold  the bottom half (assuming a default
  3149.      OPTION  BASE=0).   So,  you  would  tell  PUTSCREEN to start with array
  3150.      element  SCRN(1000),  and  give  it the starting and ending coordinates
  3151.      of the corners of the lower half of the screen.
  3152.           Parameters specifications are the same as they are for GETSCREEN.
  3153.  
  3154.      Example:
  3155.           CALL PUTSCREEN(SCRN(0),TOPROW,LFTCOL,BOTROW,RGTCOL,PAGE,SCRNMODE)
  3156.  
  3157.  
  3158.  
  3159.  
  3160.  
  3161.  
  3162.  
  3163.  
  3164.  
  3165.  
  3166.  
  3167.  
  3168.  
  3169.  
  3170.  
  3171.  
  3172.  
  3173.  
  3174.  
  3175.  
  3176.  
  3177.  
  3178.  
  3179.      Name: QPRINT
  3180.  
  3181.      Type: Video / CLONE
  3182.  
  3183.      Description:
  3184.           This  function  bypasses  the  usual  video routines, and prints a
  3185.      string directly on the screen, at a -much- higher speed than the normal
  3186.      PRINT  statement  does.   It also contains a built-in LOCATE statement,
  3187.      and  doesn't  affect the cursor position.  Note that control characters
  3188.      will  show  up  as graphics characters instead of having their original
  3189.      functions,  and  the  color/attributes  used  will  be the ones already
  3190.      on  the  screen.   Display  page zero is used with color adapters.  See
  3191.      also XQPRINT.
  3192.  
  3193.      Example:
  3194.           ST$ = "This is a test of fast screen printing"
  3195.           ROW = 10: COL = 20
  3196.           CALL QPRINT(ST$,ROW,COL)
  3197.  
  3198.  
  3199.  
  3200.  
  3201.  
  3202.  
  3203.  
  3204.  
  3205.  
  3206.  
  3207.  
  3208.  
  3209.  
  3210.  
  3211.  
  3212.  
  3213.  
  3214.  
  3215.  
  3216.  
  3217.  
  3218.  
  3219.  
  3220.  
  3221.  
  3222.  
  3223.  
  3224.  
  3225.  
  3226.  
  3227.  
  3228.  
  3229.  
  3230.  
  3231.  
  3232.  
  3233.  
  3234.  
  3235.  
  3236.  
  3237.  
  3238.  
  3239.  
  3240.  
  3241.  
  3242.  
  3243.  
  3244.  
  3245.      Name: READBITF
  3246.  
  3247.      Type: Miscellaneous / ANY
  3248.  
  3249.      Description:
  3250.           Reads  a  word  from  an  array  of arbitrary bit length, given an
  3251.      index.   The  words  in  the  array  may  be made of one to eight bits.
  3252.      Indices  begin  at  zero  and are limited by integer range.  That is up
  3253.      to  &HFFFF,  subject  to  memory constraints-- the index is taken to be
  3254.      an  unsigned integer value.  This function allows very memory-efficient
  3255.      storage  of  arrays  of  numbers,  provided that the numbers are within
  3256.      a  restricted  range.   The  simulated  array  is  held within a normal
  3257.      integer  array,  which  must  be  dimensioned  large enough to hold all
  3258.      of  the arbitrary-length words (will depend on bits per word and number
  3259.      of words desired).
  3260.  
  3261.      Example:
  3262.           OPTION BASE 0: DEFINT A-Z: DIM INTARRAY(50): BITFSIZE=8
  3263.             .
  3264.             .
  3265.           ARRAYLOC=VARPTR(INTARRAY(0))
  3266.           CALL READBITF(ARRAYLOC,NDX,BITFSIZE,VALUE)
  3267.           REM  Returns a value from the array location indexed by NDX,
  3268.           REM  where the array is composed of bytes (8-bit words).
  3269.           REM  See the disk file BITFTEST.BAS in the source files
  3270.           REM  for a working example program (compiled BASIC only!)
  3271.  
  3272.  
  3273.  
  3274.  
  3275.      Name: RECOLOR
  3276.  
  3277.      Type: Video / CLONE
  3278.  
  3279.      Description:
  3280.           Takes everything on the screen that's of a given color and changes
  3281.      its  color to whatever you like.  This can be used for special effects,
  3282.      or  just to change the screen color without having to clear the screen.
  3283.      This will work only in text mode.  The color attributes must be defined
  3284.      from the foreground and background colors using the CALCATTR routine.
  3285.  
  3286.      Example:
  3287.           CALL CALCATTR(FOREGND,BACKGND,OLDCOLR)
  3288.           CALL CALCATTR(NEWFORE,NEWBACK,NEWCOLR)
  3289.           CALL RECOLOR(OLDCOLR,NEWCOLR)
  3290.  
  3291.  
  3292.  
  3293.  
  3294.  
  3295.  
  3296.  
  3297.  
  3298.  
  3299.  
  3300.  
  3301.  
  3302.  
  3303.  
  3304.  
  3305.  
  3306.  
  3307.  
  3308.  
  3309.  
  3310.  
  3311.      Name: RESETPOINT
  3312.  
  3313.      Type: Video / BIOS
  3314.  
  3315.      Description:
  3316.           Resets a point on a text screen.  This is the opposite of SETPOINT
  3317.      (see).
  3318.  
  3319.      Example:
  3320.           ROW=0
  3321.           FOR COLUMN=0 to 79
  3322.              CALL RESETPOINT(COLUMN,ROW)
  3323.           NEXT COLUMN
  3324.           REM  this clears a line from the top of the screen
  3325.           REM  (undoes the line from the SETPOINT example)
  3326.  
  3327.  
  3328.  
  3329.  
  3330.      Name: REVERSE
  3331.  
  3332.      Type: String / ANY
  3333.  
  3334.      Description:
  3335.           Reverses  the  order  of  characters  in  a  string.   This can be
  3336.      combined with the XLATE function and a judiciously-designed translation
  3337.      table  to provide mirror images of strings for character-graphics-based
  3338.      displays.   It  can also be used with INSTR to provide a function which
  3339.      returns the last occurrence of a given substring within a string.
  3340.  
  3341.      Example:
  3342.           MSG$="This is a test": CALL REVERSE(MSG$): PRINT MSG$
  3343.  
  3344.  
  3345.  
  3346.  
  3347.      Name: RROTATE
  3348.  
  3349.      Type: String / ANY
  3350.  
  3351.      Description:
  3352.           Rotates  the  characters  in  a string right.  This is the same as
  3353.      LROTATE, only in reverse.  See LROTATE for further details.
  3354.  
  3355.      Example:
  3356.           ST$ = "12345": CALL RROTATE(ST$)
  3357.           REM  ST$ will end up being "51234"
  3358.  
  3359.  
  3360.  
  3361.  
  3362.  
  3363.  
  3364.  
  3365.  
  3366.  
  3367.  
  3368.  
  3369.  
  3370.  
  3371.  
  3372.  
  3373.  
  3374.  
  3375.  
  3376.  
  3377.      Name: SCROLL
  3378.  
  3379.      Type: Video / BIOS
  3380.  
  3381.      Description:
  3382.           Scrolls  any  selected  portion of the screen as many times as you
  3383.      like
  3384.      (or  use  0 to clear that part of the screen entirely).  There are five
  3385.      parameters  to this function: coordinates (LEFTCOL,TOPROW) of the upper
  3386.      left  corner  of  the  area  to be scrolled, coordinates (RTCOL,BOTROW)
  3387.      of  the  lower  right corner of the area to be scrolled, and the number
  3388.      of  times  to scroll the area.  This routine may be used to create win-
  3389.      dows.   Note  that  RTCOL must be at least one greater than LEFTCOL (no
  3390.      single-line  scrolling,  obviously).   Note  also  that  you should not
  3391.      try  to  scroll  more  times  than  there  are  lines in the area to be
  3392.      scrolled  (use  0  instead).  Parameters are not checked, so be careful
  3393.      not to use illegal screen coordinates.
  3394.  
  3395.      Example:
  3396.           CALL SCROLL(LEFTCOL,TOPROW,RTCOL,BOTROW,NUMLINES)
  3397.  
  3398.  
  3399.  
  3400.  
  3401.  
  3402.  
  3403.  
  3404.  
  3405.  
  3406.  
  3407.  
  3408.  
  3409.  
  3410.  
  3411.  
  3412.  
  3413.  
  3414.  
  3415.  
  3416.  
  3417.  
  3418.  
  3419.  
  3420.  
  3421.  
  3422.  
  3423.  
  3424.  
  3425.  
  3426.  
  3427.  
  3428.  
  3429.  
  3430.  
  3431.  
  3432.  
  3433.  
  3434.  
  3435.  
  3436.  
  3437.  
  3438.  
  3439.  
  3440.  
  3441.  
  3442.  
  3443.      Name: SCRREST
  3444.  
  3445.      Type: Video / CLONE
  3446.  
  3447.      Description:
  3448.           Restores  the  screen  display  from an image put into an array by
  3449.      SCRSAVE.  Same requirements and limitations of SCRSAVE.
  3450.  
  3451.      Example:
  3452.           WHERE = VARPTR(SCR(1)): CALL SCRREST(WHERE): LOCATE OLDROW,OLDCOL
  3453.  
  3454.  
  3455.  
  3456.  
  3457.      Name: SCRSAVE
  3458.  
  3459.      Type: Video / CLONE
  3460.  
  3461.      Description:
  3462.           Stores  the  current  screen  display  (page  0 only) in an array.
  3463.      Text  modes  only.   Requires  an  array  of 4000 bytes, and an integer
  3464.      which  points  to  the  location  of the array.  The cursor position is
  3465.      not saved.
  3466.  
  3467.      Example:
  3468.           DEFINT A-Z: OPTION BASE 1: DIM SCR(2000)
  3469.            .
  3470.            .
  3471.           WHERE = VARPTR(SCR(1)): CALL SCRSAVE(WHERE)
  3472.           OLDCOL = POS(0) : OLDROW = CSRLIN
  3473.           REM  Dim of 2000 w/ option base 1 gives us 2000 integers,
  3474.           REM  which gives us 4000 bytes of storage space.
  3475.           REM  Note: you can store more than one screen in an array by
  3476.           REM  dimensioning it large enough.  Use WHERE=VARPTR(SCR(2001))
  3477.           REM  to locate the second screen, and so forth.
  3478.  
  3479.  
  3480.  
  3481.  
  3482.  
  3483.  
  3484.  
  3485.  
  3486.  
  3487.  
  3488.  
  3489.  
  3490.  
  3491.  
  3492.  
  3493.  
  3494.  
  3495.  
  3496.  
  3497.  
  3498.  
  3499.  
  3500.  
  3501.  
  3502.  
  3503.  
  3504.  
  3505.  
  3506.  
  3507.  
  3508.  
  3509.      Name: SCRRESTP, SCRRESTPD, SCRSAVEP, SCRSAVEPD
  3510.  
  3511.      Type: Video / CLONE
  3512.  
  3513.      Description:
  3514.           These  functions  are  variations  of SCRREST and SCRSAVE.  All of
  3515.      them  allow  specification  of a page number, for color monitors.  They
  3516.      will  save  or restore text to a given page.  When used with monochrome
  3517.      monitors,  the  page  specification  should  always be zero.  SCRRESTPD
  3518.      and  SCRSAVEPD  write  directly to the screen at high speed.  This will
  3519.      cause  "snow"  if  you  have  an  old  or poorly designed color display
  3520.      adapter  and  are  writing  to  the  active  screen  page.  Under those
  3521.      conditions, you should use SCRRESTP/SCRSAVEP or SCRREST/SCRSAVE.
  3522.  
  3523.      Example:
  3524.           WHERE = VARPTR(SCR(1)) : SCRNPAGE = 0
  3525.           CALL SCRRESTP(WHERE,SCRNPAGE) : LOCATE OLDROW,OLDCOL
  3526.  
  3527.  
  3528.  
  3529.  
  3530.  
  3531.  
  3532.  
  3533.  
  3534.  
  3535.  
  3536.  
  3537.  
  3538.  
  3539.  
  3540.  
  3541.  
  3542.  
  3543.  
  3544.  
  3545.  
  3546.  
  3547.  
  3548.  
  3549.  
  3550.  
  3551.  
  3552.  
  3553.  
  3554.  
  3555.  
  3556.  
  3557.  
  3558.  
  3559.  
  3560.  
  3561.  
  3562.  
  3563.  
  3564.  
  3565.  
  3566.  
  3567.  
  3568.  
  3569.  
  3570.  
  3571.  
  3572.  
  3573.  
  3574.  
  3575.      Name: SETCOMM
  3576.  
  3577.      Type: Miscellaneous / CLONE
  3578.  
  3579.      Description:
  3580.           Sets   communications   parameters  on  an  opened  communications
  3581.      device.  This allows you to set the baud rate higher than BASIC normal-
  3582.      ly  allows,  and  to change the comm parameters without having to close
  3583.      the comm device.
  3584.           Note  that  BASIC  currently  limits  access to comm ports one and
  3585.      two.   You can set parms on ports 1-4 using SETCOMM, however.  Possibly
  3586.      a  future  release  of ADVBAS will allow you to use the other two ports
  3587.      if you have them.
  3588.           Why  is  it  bad  to  have to close the comm device?  Because that
  3589.      will  make  the  DTR  signal drop, which will cause many modems to drop
  3590.      the  carrier and lose your connection.  In fact, for Hayes-type modems,
  3591.      that's  a  much  more reliable way to end communications than using the
  3592.      ATH "hang up modem" command.
  3593.           If  you  try  to  set  a  comm port which does not exist, the port
  3594.      number  will  be set to zero after the call.  If you give illegal para-
  3595.      meters  elsewhere,  the port will be set to a default of 300 baud, Even
  3596.      parity,  Seven-bit  words,  and  One  stop  bit (any of the parms which
  3597.      were legal will be used).
  3598.  
  3599.      Example:
  3600.           OPEN"R",1,"COM1:300,E,7,1,RS,CS,DS"
  3601.           COMMPORT = 1 : BPS = 6 : PARITY = 0 : WORDLENGTH = 8
  3602.           STOPBITS = 1
  3603.           CALL SETCOMM(COMMPORT,BPS,PARITY,WORDLENGTH,STOPBITS)
  3604.           REM  sets the port to 19200 baud, No parity, 8 bit words
  3605.           REM  and 1 stop bit.
  3606.  
  3607.      Settings:
  3608.           COMMPORT  may be 1 - 2, and will be returned as 0 if the specified
  3609.      port doesn't exist.
  3610.           BPS  ("baud  rate")  is  specified  by a number from 0 - 7.  Use 0
  3611.      for  300  bps,  1  for  600,  2 for 1200, 3 for 2400, 4 for 4800, 5 for
  3612.      9600,  6  for  19200,  and  7  for 38400 bps.  Whether you can actually
  3613.      get speeds over 9600 will depend on the quality of your comm port.
  3614.           PARITY is a number 0-2.  Use 0 for None, 1 for Odd, 2 for Even.
  3615.           WORDLENGTH may be 7 or 8, and STOPBITS may be 1 or 2.
  3616.  
  3617.  
  3618.  
  3619.  
  3620.  
  3621.  
  3622.  
  3623.  
  3624.  
  3625.  
  3626.  
  3627.  
  3628.  
  3629.  
  3630.  
  3631.  
  3632.  
  3633.  
  3634.  
  3635.  
  3636.  
  3637.  
  3638.  
  3639.  
  3640.  
  3641.      Name: SETDRV
  3642.  
  3643.      Type: Disk / DOS
  3644.  
  3645.      Description:
  3646.           Sets  the  default  drive.   The drive string must be at least one
  3647.      character long, and start with a letter specifying a disk drive.
  3648.  
  3649.      Example:
  3650.           DRV$="B:"
  3651.                .
  3652.                .
  3653.           CALL SETDRV(DRV$)
  3654.  
  3655.  
  3656.  
  3657.  
  3658.      Name: SETFATTR
  3659.  
  3660.      Type: Disk / DOS
  3661.  
  3662.      Description:
  3663.           Sets  the attribute of a file.  See the section on file attributes
  3664.      at the end of this manual.
  3665.  
  3666.      Example:
  3667.           FIL$ = FIL$+CHR$(0): CALL SETFATTR(FIL$,ATTR)
  3668.  
  3669.  
  3670.  
  3671.  
  3672.      Name: SETFTD
  3673.  
  3674.      Type: Disk / DOS
  3675.  
  3676.      Description:
  3677.           Sets  file  time/date stamp.  The filename must be terminated with
  3678.      a  NUL  character.   The  year  may be either a four digit or two digit
  3679.      number  (e.g.,  either  1986  or  just 86).  DOS will round the seconds
  3680.      value  off  to  the next lower even number.  If there is a problem with
  3681.      the filename, the month will be returned as -1.
  3682.  
  3683.      Example:
  3684.           FIL$=FIL$+CHR$(0)
  3685.           CALL SETFTD(FIL$,MONTH,DAY,YEAR,HOUR,MINUTE,SECOND)
  3686.           IF MONTH=-1 THEN PRINT "No such file"
  3687.  
  3688.  
  3689.  
  3690.  
  3691.  
  3692.  
  3693.  
  3694.  
  3695.  
  3696.  
  3697.  
  3698.  
  3699.  
  3700.  
  3701.  
  3702.  
  3703.  
  3704.  
  3705.  
  3706.  
  3707.      Name: SETMATI
  3708.  
  3709.      Type: Miscellaneous / ANY
  3710.  
  3711.      Description:
  3712.           Sets  the  first  SIZ  elements  of  an  integer  array to a given
  3713.      (scalar)  value,  INITVAL.   It  will work on multi-dimensional arrays,
  3714.      in  which  case  the leftmost dimension increments first (unless you've
  3715.      set  the  compiler  option  telling  it to do otherwise).  See examples
  3716.      for clarification.
  3717.  
  3718.      Example:
  3719.           OPTION BASE 0: DEFINT A-Z: DIM BANANA(9)
  3720.           SIZ=10: INITVAL=-3: ARLOC=VARPTR(BANANA(0))
  3721.           CALL SETMATI(ARLOC,SIZ,INITVAL)
  3722.           REM  we have just initialized all 10 elements of the array to
  3723.           REM  the value -3.
  3724.  
  3725.      Example:
  3726.           OPTION BASE 1: DEFINT A-Z: DIM FOO(3,5)
  3727.           SIZ=5: INITVAL=20000: ARLOC=VARPTR(FOO(1,1))
  3728.           CALL SETMATI(ARLOC,SIZ,INITVAL)
  3729.           REM  we have just set the first five elements of the array to
  3730.           REM  20000.  The first five elements are FOO(1,1), FOO(2,1),
  3731.           REM  FOO(3,1), FOO(1,2), FOO(2,2).  If you wanted to initialize
  3732.           REM  the whole array to 20000, you'd set SIZ=3*5 for OPTION BASE 1
  3733.           REM  or SIZ=(3+1)*(5+1) for OPTION BASE 0, in this case...
  3734.           REM  By changing the first element (in the ARLOC assignment), you
  3735.           REM  can set any part of the array, not just the first elements.
  3736.           REM  See SCRSAVE/SCRREST if you need to clear up that last point.
  3737.  
  3738.  
  3739.  
  3740.  
  3741.  
  3742.  
  3743.  
  3744.  
  3745.  
  3746.  
  3747.  
  3748.  
  3749.  
  3750.  
  3751.  
  3752.  
  3753.  
  3754.  
  3755.  
  3756.  
  3757.  
  3758.  
  3759.  
  3760.  
  3761.  
  3762.  
  3763.  
  3764.  
  3765.  
  3766.  
  3767.  
  3768.  
  3769.  
  3770.  
  3771.  
  3772.  
  3773.      Name: SETKBD
  3774.  
  3775.      Type: Input / CLONE
  3776.  
  3777.      Description:
  3778.           Sets  the  status  of  the keyboard toggles.  The toggle is set on
  3779.      if  the  value  is  nonzero,  and off if the value is zero.  Good style
  3780.      suggests  that,  before  using  this  function  for the first time, you
  3781.      should  get  the  toggles  with GETKBD (see) and save them.  You should
  3782.      then  restore  the  keyboard  to that original state before exiting the
  3783.      program.
  3784.  
  3785.      Example:
  3786.           REM  Let's turn off Insert, Caps Lock, and Scroll Lock
  3787.           REM  and put the keypad into numeric mode by turning on Num Lock
  3788.           INSERT=0: CAPSLOCK=0: NUMLOCK=1: SCROLLLOCK=0
  3789.           CALL SETKBD(INSERT,CAPSLOCK,NUMLOCK,SCROLLLOCK)
  3790.  
  3791.  
  3792.  
  3793.  
  3794.      Name: SETPOINT
  3795.  
  3796.      Type: Video / BIOS
  3797.  
  3798.      Description:
  3799.           Sets  a  point  on  a  text  screen.   This  allows low-resolution
  3800.      graphics  on  monochrome  as  well  as color monitors.  Normal text can
  3801.      also  be  mixed  with  the graphics.  Resolution is 80x50 (0-79 columns
  3802.      by 0-49 rows).  See also RESETPOINT and TESTPOINT.
  3803.  
  3804.      Example:
  3805.           ROW=24
  3806.           FOR COLUMN=0 TO 79
  3807.              CALL SETPOINT(COLUMN,ROW)
  3808.           NEXT COLUMN
  3809.           REM  this draws a line across the middle of the screen.
  3810.  
  3811.  
  3812.  
  3813.  
  3814.      Name: SETSUB
  3815.  
  3816.      Type: Disk / DOS
  3817.  
  3818.      Description:
  3819.           Sets  the  default  subdirectory.   The  subdirectory  string must
  3820.      be  terminated  by  a  NUL character.  An error will be returned if the
  3821.      specified subdirectory doesn't exist.
  3822.  
  3823.      Example:
  3824.           TMP$ = SUB$+CHR$(0): CALL SETSUB(TMP$,ERRCODE)
  3825.           IF ERRCODE THEN bad subdir ELSE new default subdir selected
  3826.  
  3827.  
  3828.  
  3829.  
  3830.  
  3831.  
  3832.  
  3833.  
  3834.  
  3835.  
  3836.  
  3837.  
  3838.  
  3839.      Name: SHIFTL
  3840.  
  3841.      Type: Miscellaneous / ANY
  3842.  
  3843.      Description:
  3844.           Shifts all the bits in an integer left COUNT times, putting zeroes
  3845.      in  the bit positions which have been vacated.  This effectively multi-
  3846.      plies  the  value  by  a power of two in most instances.  This function
  3847.      is  included  for  those  advanced  programmers who know what it's good
  3848.      for...
  3849.  
  3850.      Example:
  3851.           VALUE = 47: COUNT = 3
  3852.           CALL SHIFTL(VALUE,COUNT)
  3853.           REM  we just shifted VALUE left three bits
  3854.           REM  (in this case getting 47 * 2^3, or 376)
  3855.  
  3856.  
  3857.  
  3858.  
  3859.      Name: SHIFTR
  3860.  
  3861.      Type: Miscellaneous / ANY
  3862.  
  3863.      Description:
  3864.           Same  as  SHIFTL, but shifts the bits right instead of left.  This
  3865.      is similar in effect to an integer divide by a power of two.
  3866.  
  3867.      Example:
  3868.           VALUE = 47: COUNT = 3
  3869.           CALL SHIFTR(VALUE,COUNT)
  3870.           REM  we just shifted VALUE right 3 bits
  3871.           REM  (here getting 47 \ 2^3, or 5)
  3872.  
  3873.  
  3874.  
  3875.  
  3876.  
  3877.  
  3878.  
  3879.  
  3880.  
  3881.  
  3882.  
  3883.  
  3884.  
  3885.  
  3886.  
  3887.  
  3888.  
  3889.  
  3890.  
  3891.  
  3892.  
  3893.  
  3894.  
  3895.  
  3896.  
  3897.  
  3898.  
  3899.  
  3900.  
  3901.  
  3902.  
  3903.  
  3904.  
  3905.      Name: SOUNDEX
  3906.  
  3907.      Type: String / ANY
  3908.  
  3909.      Description:
  3910.           This  routine  returns  the Soundex code for a string you give it.
  3911.      I'm  not sure who invented Soundex, but it's pretty handy.  The Soundex
  3912.      routine  takes  a  word  and returns a string which represents what the
  3913.      word  sounds  like  in  an abstract format.  Similar-sounding words can
  3914.      thus  be  identified  easily  by your program after Soundex processing.
  3915.      This  can  be  useful in applications where a person is not sure of the
  3916.      exact  spelling  of  a  word/name/city,  etc.   To use, put the word in
  3917.      WORD$, initialize the return string SCODE$ to the same length as WORD$,
  3918.      and  execute  the  routine.   SLEN%  will  return  the actual length of
  3919.      SCODE$,  which  may  vary  from zero to the length of WORD$.  If SCODE$
  3920.      is  not  as  long  as  WORD$  when the routine is called, SLEN% will be
  3921.      returned  as  -1  to  flag  an  error.  The Soundex code is returned as
  3922.      a  series  of  digits  in  SCODE$,  although you can represent this any
  3923.      way you choose in your program.
  3924.  
  3925.      Example:
  3926.           WORD$ = "AnyWord": SCODE$=WORD$: CALL SOUNDEX(WORD$,SCODE$,SLEN)
  3927.           PRINT"The Soundex code for ";WORD$;" is ";LEFT$(SCODE$,SLEN);"."
  3928.           REM  Try this routine a few times to get a feel for it.
  3929.  
  3930.  
  3931.  
  3932.  
  3933.      Name: SPEAKER
  3934.  
  3935.      Type: Miscellaneous / CLONE
  3936.  
  3937.      Description:
  3938.           This  function  allows  you  to  turn the speaker on or off.  This
  3939.      allows you to disable sound effects for a program.  Your sound routines
  3940.      will  still  be  executed,  but  will not produce any sound if you have
  3941.      turned  the  speaker off.  Thus, your routines will execute at the same
  3942.      speed  whether  or  not  sound is turned on, and the timing will remain
  3943.      the same.  Note that you should turn the speaker back on before exiting
  3944.      the program!
  3945.           Use zero to turn off the speaker, nonzero to turn it back on.
  3946.           NOTE: This  function  appears  to be erratic, especially when used
  3947.      with  slightly  incompatible  machines  such as the AT.  It is unlikely
  3948.      to work on a PCjr.  Test it to see if it works for you.
  3949.  
  3950.      Example:
  3951.           SPKR = 0
  3952.           CALL SPEAKER(SPKR)
  3953.           REM  turn the speaker off
  3954.  
  3955.  
  3956.  
  3957.  
  3958.  
  3959.  
  3960.  
  3961.  
  3962.  
  3963.  
  3964.  
  3965.  
  3966.  
  3967.  
  3968.  
  3969.  
  3970.  
  3971.      Name: STRIP
  3972.  
  3973.      Type: String / ANY
  3974.  
  3975.      Description:
  3976.           Strips  all  occurrences  of a given target character from a given
  3977.      source  string.   The  target  string must be at least one character in
  3978.      length (if more, the first character will be used).
  3979.  
  3980.      Example:
  3981.           MSG$="12 - 2 =   10"
  3982.             .
  3983.             .
  3984.           CH$=" ": CALL STRIP(MSG$,CH$,MLEN): MSG$ = LEFT$(MSG$,MLEN)
  3985.  
  3986.  
  3987.  
  3988.  
  3989.      Name: STRIPBLANKS
  3990.  
  3991.      Type: String / ANY
  3992.  
  3993.      Description:
  3994.           Strips  blanks  (and  control  characters) from either the left or
  3995.      right  side of a string, or both sides.  Specify 0 (zero) for no strip,
  3996.      1 to strip left, 2 to strip right, or 3 to strip both sides.
  3997.  
  3998.      Example:
  3999.           STRIPWHICH = 3 : REM strip both sides of blanks
  4000.           CALL STRIPBLANKS(ST$,STRIPWHICH,SLEN)
  4001.           ST$ = LEFT$(ST$,SLEN)
  4002.  
  4003.  
  4004.  
  4005.  
  4006.  
  4007.  
  4008.  
  4009.  
  4010.  
  4011.  
  4012.  
  4013.  
  4014.  
  4015.  
  4016.  
  4017.  
  4018.  
  4019.  
  4020.  
  4021.  
  4022.  
  4023.  
  4024.  
  4025.  
  4026.  
  4027.  
  4028.  
  4029.  
  4030.  
  4031.  
  4032.  
  4033.  
  4034.  
  4035.  
  4036.  
  4037.      Name: STRIPRANGE
  4038.  
  4039.      Type: String / ANY
  4040.  
  4041.      Description:
  4042.           Strips all characters within a given range out of a source string.
  4043.  
  4044.      Example:
  4045.           MSG$="ALL uppercase letters will be G-O-N-E gone"
  4046.           LO = ASC("A"): HI = ASC("Z")
  4047.           CALL STRIPRANGE(MSG$,LO,HI,MLEN)
  4048.           MSG$ = LEFT$(MSG$,MLEN)
  4049.  
  4050.  
  4051.  
  4052.  
  4053.      Name: SUBEXIST
  4054.  
  4055.      Type: Disk / DOS
  4056.  
  4057.      Description:
  4058.           Tests  to  see  if  a  given subdirectory exists.  You may include
  4059.      a  drive  spec  in  the  subdirectory name, which must be terminated by
  4060.      a null.
  4061.  
  4062.      Example:
  4063.           SUBDIR$ = "C:\TEMP" + CHR$(0)
  4064.           CALL SUBEXIST(SUBDIR$,VALID)
  4065.           IF VALID THEN PRINT"Subdirectory exists"
  4066.           ELSE PRINT"No such subdirectory"
  4067.  
  4068.  
  4069.  
  4070.  
  4071.  
  4072.  
  4073.  
  4074.  
  4075.  
  4076.  
  4077.  
  4078.  
  4079.  
  4080.  
  4081.  
  4082.  
  4083.  
  4084.  
  4085.  
  4086.  
  4087.  
  4088.  
  4089.  
  4090.  
  4091.  
  4092.  
  4093.  
  4094.  
  4095.  
  4096.  
  4097.  
  4098.  
  4099.  
  4100.  
  4101.  
  4102.  
  4103.      Name: TESTPOINT
  4104.  
  4105.      Type: Video / BIOS
  4106.  
  4107.      Description:
  4108.           Tests  a  pixel  on  a  text  screen to see if it's on or off (see
  4109.      SETPOINT  for  information  about  text  graphics).  The value returned
  4110.      will be set if the point is set, or reset if the point is not set.
  4111.  
  4112.      Example:
  4113.           COL=39: ROW=24: REM  check a point near the middle of the screen
  4114.           CALL TESTPOINT(COL,ROW,STATUS)
  4115.           IF STATUS THEN PRINT"The point is lit"
  4116.           ELSE PRINT"The point is not lit"
  4117.  
  4118.  
  4119.  
  4120.  
  4121.      Name: TIME2INT
  4122.  
  4123.      Type: Miscellaneous / ANY
  4124.  
  4125.      Description:
  4126.           Squeezes  the  time  down to a single integer, for reduced storage
  4127.      requirements.   You  will lose some accuracy in the seconds, which will
  4128.      be  converted  to  an  even  number (odd numbers will be rounded down).
  4129.      To  avoid  ambiguity,  it  is  recommended that you specify hours using
  4130.      a 24-hour clock.  See also INT2TIME.
  4131.  
  4132.      Example:
  4133.           CALL(HOUR,MIN,SEC,SQZTIME)
  4134.  
  4135.  
  4136.  
  4137.  
  4138.      Name: TIMEN2S
  4139.  
  4140.      Type: String / ANY
  4141.  
  4142.      Description:
  4143.           Converts  the  time  from  numbers to a string.  The string should
  4144.      be at least eight characters long.  See also TIMES2N.
  4145.  
  4146.      Example:
  4147.           HOUR=13: MIN=30: SEC=48: TIM$=SPACE$(8)
  4148.           CALL TIMEN2S(HOUR,MIN,SEC,TIM$)
  4149.           REM  We get TIM$ = "13:30:48" from this
  4150.  
  4151.  
  4152.  
  4153.  
  4154.  
  4155.  
  4156.  
  4157.  
  4158.  
  4159.  
  4160.  
  4161.  
  4162.  
  4163.  
  4164.  
  4165.  
  4166.  
  4167.  
  4168.  
  4169.      Name: TIMES2N
  4170.  
  4171.      Type: String / ANY
  4172.  
  4173.      Description:
  4174.           Converts  the  time  from  a  string  to numbers.  The seconds are
  4175.      optional, and will be set to zero if nonexistent.
  4176.  
  4177.      Example:
  4178.           TIM$ = "13:09:42"
  4179.           CALL TIMES2N(HOUR,MIN,SEC,TIM$)
  4180.           REM  We get HOUR=13, MIN=9, SEC=42
  4181.           TIM$ = "03:15"
  4182.           CALL TIMES2N(HOUR,MIN,SEC,TIM$)
  4183.           REM  We get HOUR=3, MIN=15, SEC=0
  4184.  
  4185.  
  4186.  
  4187.  
  4188.      Name: TINSTR
  4189.  
  4190.      Type: STRING / ANY
  4191.  
  4192.      Description:
  4193.           Allows  you  to  search  for  a  given  type of character within a
  4194.      string.   You  may  search for any of several character types by adding
  4195.      the  values of the types to search for.  This also allows you to search
  4196.      for  the  opposite  of  a  character type (that is, search for anything
  4197.      other than that type).
  4198.  
  4199.      Character types:
  4200.      1
  4201.           Alphabetic  A-Z, a-z
  4202.      2
  4203.           Numeric     0-9
  4204.      4
  4205.           Symbolic    (anything not covered by other types)
  4206.      8
  4207.           Control     (control codes: ASCII 0-31, 127)
  4208.      16
  4209.           Graphics    (PC graphics codes: 128-255)
  4210.      32
  4211.           Blank       (a blank space, ASCII 32)
  4212.  
  4213.      Example:
  4214.           CHRTYPE = 1+2+4+8+16  : REM search for first non-blank character
  4215.           CALL TINSTR(ST$,CHRTYPE,PLACE)
  4216.           IF PLACE=0 THEN PRINT "The string contains no non-blank chars"
  4217.           ELSE PRINT "The first nonblank character is at location";PLACE;"."
  4218.  
  4219.      Example:
  4220.           CHRTYPE = 2  : REM search for first numeric character
  4221.           ST$ = "Springfield, VA 22152"
  4222.           CALL TINSTR(ST$,CHRTYPE,PLACE)
  4223.           PRINT "The zip code is: ";MID$(ST$,PLACE,5)
  4224.  
  4225.  
  4226.  
  4227.  
  4228.  
  4229.  
  4230.  
  4231.  
  4232.  
  4233.  
  4234.  
  4235.  
  4236.  
  4237.  
  4238.  
  4239.  
  4240.  
  4241.      Name: UPCASE
  4242.  
  4243.      Type: String / ANY
  4244.  
  4245.      Description:
  4246.           Converts a string to all uppercase.
  4247.  
  4248.      Example:
  4249.           MSG$="Four score and seven years ago"
  4250.             .
  4251.             .
  4252.           CALL UPCASE(MSG$)
  4253.  
  4254.  
  4255.  
  4256.  
  4257.  
  4258.  
  4259.  
  4260.  
  4261.  
  4262.  
  4263.  
  4264.  
  4265.  
  4266.  
  4267.  
  4268.  
  4269.  
  4270.  
  4271.  
  4272.  
  4273.  
  4274.  
  4275.  
  4276.  
  4277.  
  4278.  
  4279.  
  4280.  
  4281.  
  4282.  
  4283.  
  4284.  
  4285.  
  4286.  
  4287.  
  4288.  
  4289.  
  4290.  
  4291.  
  4292.  
  4293.  
  4294.  
  4295.  
  4296.  
  4297.  
  4298.  
  4299.  
  4300.  
  4301.  
  4302.  
  4303.  
  4304.  
  4305.  
  4306.  
  4307.      Name: WEEKDAY
  4308.  
  4309.      Type: Miscellaneous / DOS
  4310.  
  4311.      Description:
  4312.           Returns  an  integer  from  1  - 7 indicating the day of the week,
  4313.      Sunday  through  Saturday.  The example routine turns this integer into
  4314.      the week day.
  4315.  
  4316.      Example:
  4317.           CALL WEEKDAY(DAY%)
  4318.           DLEN% = VAL(MID$("3346535",DAY,1))
  4319.           DLOC% = ASC(MID$("ADGKQVY",DAY%))-64
  4320.           REM  The above string MUST be in uppercase!
  4321.           PRINT "Today is";
  4322.           PRINT MID$("SunMonTuesWednesThursFriSatur",DLOC%,DLEN%);"day."
  4323.  
  4324.  
  4325.  
  4326.  
  4327.      Name: WRITEBITF
  4328.  
  4329.      Type: Miscellaneous / ANY
  4330.  
  4331.      Description:
  4332.           Allows  a value to be written into a given location of a simulated
  4333.      array  of  words  of  arbitrary  bit  length (1-8 bits per word).  This
  4334.      goes  with  the  READBITF function above.  The "BITF" is for Bit Field,
  4335.      because  the  functions work by creating fields of arbitrary bit length
  4336.      within what is actually an integer array.
  4337.  
  4338.      Example:
  4339.           CALL WRITEBITF(ARRAYLOC,INDEX,BITFSIZE,VALUE)
  4340.           REM  See the READBITF function, and see the BITFTEST.BAS if you
  4341.           REM  have the ADVBAS contributor disk, to better idea of what's
  4342.           REM  going on.  This function is not for novice programmers!
  4343.  
  4344.  
  4345.  
  4346.  
  4347.  
  4348.  
  4349.  
  4350.  
  4351.  
  4352.  
  4353.  
  4354.  
  4355.  
  4356.  
  4357.  
  4358.  
  4359.  
  4360.  
  4361.  
  4362.  
  4363.  
  4364.  
  4365.  
  4366.  
  4367.  
  4368.  
  4369.  
  4370.  
  4371.  
  4372.  
  4373.      Name: XLATE
  4374.  
  4375.      Type: String / ANY
  4376.  
  4377.      Description:
  4378.           This  function  translates a string, character by character, using
  4379.      a  table  you supply.  The character's ASCII value is used as the index
  4380.      to  the  table, and the value at that location replaces the character's
  4381.      current  value.   The  character  may  be  one byte in length, in which
  4382.      case  it  will be translated, or zero bytes, in which case nothing will
  4383.      happen.   The  translation  string  must  be  256 bytes long (remember,
  4384.      strings  may  be  longer  than  255 bytes in Compiled BASIC, so this is
  4385.      ok).
  4386.  
  4387.      Example:
  4388.          XLT$ = "": FOR X=0 TO 255: XLT$=XLT$+CHR$(X): NEXT
  4389.          MID$(XLT$,1,5) = "ABCDE": CH$ = CHR$(0)
  4390.          CALL XLATE(CH$,XLT$): PRINT CH$
  4391.          REM  CH$ ends up "A", since the start of the table + zero bytes
  4392.          REM      contains "A".  We add zero bytes, because CH$ was
  4393.          REM      originally equal to CHR$(0).
  4394.  
  4395.  
  4396.  
  4397.  
  4398.      Name: XMPRINT
  4399.  
  4400.      Type: Video / BIOS
  4401.  
  4402.      Description:
  4403.           This  routine  combines the XLATE and MPRINTC functions.  It takes
  4404.      a  character,  runs  it  through  a translation table, and prints it to
  4405.      the  screen  unless  the translated value is NUL (ASCII zero).  If it's
  4406.      NUL,  no  printing  takes  place.   MS-DOS calls are used for printing,
  4407.      so  ANSI.SYS will work.  See the XLATE and MPRINTC routines for further
  4408.      information.
  4409.  
  4410.      Example:
  4411.           CALL XMPRINT(CH$,XLATE$,COL,ROW): LOCATE ROW,COL
  4412.  
  4413.  
  4414.  
  4415.  
  4416.  
  4417.  
  4418.  
  4419.  
  4420.  
  4421.  
  4422.  
  4423.  
  4424.  
  4425.  
  4426.  
  4427.  
  4428.  
  4429.  
  4430.  
  4431.  
  4432.  
  4433.  
  4434.  
  4435.  
  4436.  
  4437.  
  4438.  
  4439.      Name: XQPRINT
  4440.  
  4441.      Type: Video / CLONE
  4442.  
  4443.      Description:
  4444.           This  function  is  an  extended  version  of  QPRINT.  It is more
  4445.      flexible,  and  only  a trifle slower.  XQPRINT has two advantages over
  4446.      QPRINT: it  allows  you  to  choose  a color/attribute to use, and lets
  4447.      you  choose  a  display  page  (color/graphics  adapters  only!).   The
  4448.      attribute  ATTR  must  be  set up using the CALCATTR routine.  The page
  4449.      argument is ignored for monochrome adapters.
  4450.  
  4451.      Example:
  4452.           ST$ = "This is a test of fast screen printing"
  4453.           ROW = 10: COL = 20: PAGE = 0
  4454.           CALL CALCATTR(FOREGND,BACKGND,ATTR)
  4455.           CALL XQPRINT(ST$,ROW,COL,ATTR,PAGE)
  4456.  
  4457.  
  4458.  
  4459.  
  4460.      Name: XQPRINTD
  4461.  
  4462.      Type: Video / CLONE
  4463.  
  4464.      Description:
  4465.           This  function  is  identical  to  XQPRINT, with the one exception
  4466.      that  it  writes  directly  to  the  screen.  That makes it even faster
  4467.      than XQPRINT, but
  4468.      means  that  it  will  cause  snow on some color monitors when printing
  4469.      to the active display page.
  4470.  
  4471.  
  4472.  
  4473.  
  4474.  
  4475.  
  4476.  
  4477.  
  4478.  
  4479.  
  4480.  
  4481.  
  4482.  
  4483.  
  4484.  
  4485.  
  4486.  
  4487.  
  4488.  
  4489.  
  4490.  
  4491.  
  4492.  
  4493.  
  4494.  
  4495.  
  4496.  
  4497.  
  4498.  
  4499.  
  4500.  
  4501.  
  4502.  
  4503.  
  4504.  
  4505.                                  File Attributes
  4506.  
  4507.  
  4508.  
  4509.  
  4510.           Every  file  has  an  "attribute byte" which tells something about
  4511.      the  file.   This  can  be  modified to some extent.  For instance, any
  4512.      file  can  be  made  "hidden", in which case it will be invisible; this
  4513.      includes  subdirectories,  which  can  still  be used even if you can't
  4514.      see  that  they're there.  Some kinds of changes are not possible, how-
  4515.      ever: you can't change a subdirectory into a normal file, for example.
  4516.  
  4517.  
  4518.      Attribute      Code      Description
  4519.  
  4520.      Normal         00h       A normal file.
  4521.      Read-only      01h       File can't be killed or rewritten.
  4522.      Hidden         02h       File disappears from view.
  4523.      System         04h       Like HIDDEN.  For system (DOS, BIOS) files.
  4524.      Volume label   08h       A disk's volume label.  Only one, in the root.
  4525.      Directory      10h       Subdirectory.
  4526.      Archive        20h       Usually set.  May be used for disk backup.
  4527.  
  4528.  
  4529.           Combinations  of  the  codes are possible, as I've mentioned.  For
  4530.      instance,  a  hidden subdirectory would have a code of 10h + 02h = 12h.
  4531.      A  normal  file,  because  of  the archive bit, might show up as either
  4532.      00h  or  20h... and  so on.  Note this is all in hexadecimal, hence the
  4533.      "h"  postfix.   Convert  to  decimal  form  as  necessary  when calling
  4534.      routines  which  use the file attribute.  BASIC has functions to handle
  4535.      this  for  you  if you don't understand hex-- see the HEX$ function and
  4536.      &H prefix in your BASIC manual.
  4537.  
  4538.           NOTE: Reading  the  volume  label is unreliable in versions of DOS
  4539.      prior to MS-DOS 3.1, due to a DOS bug.  The most secure way of handling
  4540.      it  is to do a search with the label attribute (8), then to doublecheck
  4541.      the  actual  attribute  of  the  file  (if any) which was returned.  If
  4542.      it's not the volume label, use FINDNEXTF and try again.
  4543.  
  4544.  
  4545.  
  4546.  
  4547.  
  4548.  
  4549.  
  4550.  
  4551.  
  4552.  
  4553.  
  4554.  
  4555.  
  4556.  
  4557.  
  4558.  
  4559.  
  4560.  
  4561.  
  4562.  
  4563.  
  4564.  
  4565.  
  4566.  
  4567.  
  4568.  
  4569.  
  4570.  
  4571.                               New file I/O routines
  4572.  
  4573.  
  4574.  
  4575.           This  contains  some  general  information  about the new file I/O
  4576.      routines:  FCLOSE, FCREATE, FOPEN, FREAD, FSETEND, FSETREC, and FWRITE.
  4577.  
  4578.           These  routines  duplicate  a  number  of  extant BASIC functions.
  4579.      They  are  useful,  however, for a number of reasons.  They provide you
  4580.      with  low-level  control  over  the  details  of file input and output.
  4581.      They  may  be safely used in subprograms, since they return error codes
  4582.      rather  than  using error trapping (subprograms have severe limitations
  4583.      on  use  of  error  trapping).   They  provide access to the file-level
  4584.      locking  capabilities  of  DOS  2.0 and above, which allows creation of
  4585.      programs  which  work  on normal computers as well as those with multi-
  4586.      tasking  or  networking  (BASIC's  record-level locking is incompatible
  4587.      with normal computers unless SHARE is activated).
  4588.  
  4589.           In  BASIC,  you give the file a number when you open it, and refer
  4590.      to  the  file  by that number from then on.  With the ADVBAS functions,
  4591.      you  are  given  a  "handle"  when  you open the file, which serves the
  4592.      same  purpose.  In BASIC, a file is automatically created (or truncated
  4593.      if  it  exists)  if  you open it for output.  With ADVBAS, you must use
  4594.      FCREATE  to  produce  that  result.  If you have an existing file which
  4595.      you  want  to  modify  (or  read), use FOPEN.  With ADVBAS, like BASIC,
  4596.      you  can  read  or write to a file, or move the file pointer to a given
  4597.      record or to the end of file (to append information).  Also like BASIC,
  4598.      you must close a file when you are finished using it.
  4599.  
  4600.      The error codes returned by these functions are as follows:
  4601.        -1    Unable to read or write the entire record
  4602.         2    File not found
  4603.         3    Path not found
  4604.         4    No handle available
  4605.         5    Access denied
  4606.         6    Invalid handle
  4607.        15    Invalid drive specification
  4608.  
  4609.           If  you  get  "no  handle  available", you have run out of room to
  4610.      open  files.   You  can  fix  this  by not opening so many files at the
  4611.      same  time, or by increasing the FILES=xx statement in your CONFIG.SYS.
  4612.      See your DOS manual for further information.
  4613.  
  4614.  
  4615.  
  4616.  
  4617.  
  4618.  
  4619.  
  4620.  
  4621.  
  4622.  
  4623.  
  4624.  
  4625.  
  4626.  
  4627.  
  4628.  
  4629.  
  4630.  
  4631.  
  4632.  
  4633.  
  4634.  
  4635.  
  4636.  
  4637.                                    BASCOM Bugs
  4638.  
  4639.  
  4640.  
  4641.      Microsoft QuickBASIC Compiler v1.00:
  4642.  
  4643.           If  there  is  not enough memory when you try to execute the SHELL
  4644.      command,  your program will crash.  There is no way to avoid this using
  4645.      error  trapping,  because  the  memory reallocation will have fried the
  4646.      stack.   So  even  if  you  trap  the OUT OF MEMORY error, you'll still
  4647.      crash  with  a  RETURN  WITHOUT  GOSUB if you try to return from a sub-
  4648.      routine,  or a STRING SPACE CORRUPT error when the compiler gets around
  4649.      to doing a string garbage collection.
  4650.  
  4651.           The  error  STRING FORMULA TOO COMPLEX appears erratically in some
  4652.      programs,  even  with the simplest possible string formulae.  This only
  4653.      seems to happen in programs which do a lot of string manipulation.
  4654.  
  4655.  
  4656.      Microsoft QuickBASIC Compiler v1.02:
  4657.  
  4658.           This  release  solves the SHELL crash problem.  Also, more control
  4659.      characters  are  now  printed out just like BASICA.  Many miscellaneous
  4660.      problems have been fixed...
  4661.                                    But   not  the  infamous  STRING  FORMULA
  4662.      TOO COMPLEX error.  Sigh.
  4663.  
  4664.  
  4665.  
  4666.  
  4667.  
  4668.  
  4669.  
  4670.  
  4671.  
  4672.  
  4673.  
  4674.  
  4675.  
  4676.  
  4677.  
  4678.  
  4679.  
  4680.  
  4681.  
  4682.  
  4683.  
  4684.  
  4685.  
  4686.  
  4687.  
  4688.  
  4689.  
  4690.  
  4691.  
  4692.  
  4693.  
  4694.  
  4695.  
  4696.  
  4697.  
  4698.  
  4699.  
  4700.  
  4701.  
  4702.  
  4703.  
  4704.                                    BASCOM Bugs
  4705.  
  4706.  
  4707.  
  4708.      Microsoft QuickBASIC Compiler v2.00:
  4709.  
  4710.           Well,  this  release  fixes  yet  more  compiler bugs.  The STRING
  4711.      FORMULA  TOO  COMPLEX  error  lives  on,  however.  A few new functions
  4712.      have  been added, but nothing particularly useful.  The new programming
  4713.      environment  is  poorly  designed for something which is evidently sup-
  4714.      posed  to  mimic  the "intuitive" feel of the MacIntosh (later note: it
  4715.      works  fairly  sensibly  with  a  mouse,  just  not with the keyboard).
  4716.      The  editor  is  nonstandard,  inadequate, and suffers from a number of
  4717.      irritating  bugs.   The  new  "user library feature" is a nuisance-- it
  4718.      is incompatible with standard libraries, and is poor from a developer's
  4719.      standpoint  because  you  are required to list all the names of all the
  4720.      subprograms in a library whenever you modify the library.
  4721.           The  one  thing  that  is really good about the new version of the
  4722.      compiler  is  the  manual,  which  is quite excellent-- enormous, clear
  4723.      and detailed.
  4724.  
  4725.      ANNOYANCES:
  4726.           The  editor  has  a  defective  search-and-replace  function, adds
  4727.      blank  lines  at  the  end of the program under certain conditions, and
  4728.      allows  you  to  put  some control characters directly into the program
  4729.      (which gives the compiler odd problems).
  4730.           When  entering  the  filename,  you  have  to  use Shift-Backspace
  4731.      instead of the Delete key to delete characters.  The use of TAB, SPACE,
  4732.      RETURN,  and the arrow keys when making a choice on the menus is arbit-
  4733.      rary,  weird, and counterintuitive in the extreme (later note: it works
  4734.      better  if  you  use a mouse).  If you use the old method of compiling,
  4735.      bypassing  the  new  environment, you no longer get any error messages,
  4736.      just an error count.  You can't get a source listing any more, either.
  4737.  
  4738.      BUGS:
  4739.           If  your  program  uses  error trapping, it must have at least one
  4740.      line  number in the program, even if lines are only accessed by labels.
  4741.      Otherwise,  if  you  get an error, the program crashes instead of going
  4742.      to the error handler.
  4743.           Screen paging doesn't work.
  4744.           If  you have a REMark on the same line as a DATA statement, you'll
  4745.      get peculiar error messages.
  4746.           And many more (see notes on v2.01!).
  4747.  
  4748.  
  4749.      Microsoft QuickBASIC v2.01:
  4750.  
  4751.           This  is  an  update  to v2.00, which is being distributed free of
  4752.      charge  to registered owners of QB 2.00.  It consists entirely of fixes
  4753.      to  an  amazing  number  of bugs in the v2.00 compiler, and corrections
  4754.      to errors in the manual.  Get this by all means!
  4755.  
  4756.  
  4757.  
  4758.  
  4759.  
  4760.  
  4761.  
  4762.  
  4763.  
  4764.  
  4765.  
  4766.  
  4767.  
  4768.  
  4769.  
  4770.      Wish list for Microsoft's QuickBASIC:
  4771.  
  4772.           Recursive functions and procedures ("subprograms").
  4773.           Production of code which can be linked with other languages.
  4774.           Less  outrageously  massive  overhead  for  producing  stand-alone
  4775.      programs.
  4776.           An  error  trapping function that returns the label of the routine
  4777.      where the error took place (like ERL, only for labels).
  4778.           Communications  functions  which  don't  produce  errors  whenever
  4779.      you get the slightest bit of line noise.
  4780.  
  4781.  
  4782.      Notes on Borland's Turbo BASIC v1.0:
  4783.  
  4784.           Turbo  BASIC  is almost completely compatible with BASICA/GWBASIC,
  4785.      and  fairly  compatible  with  QuickBASIC.  It supports recursive func-
  4786.      tions,  local  variables, long integers, and the 8087 chip, among other
  4787.      things.   It  has  a  fairly  slick  windowing programming environment,
  4788.      and features online, context-sensitive help.  The editor is a configur-
  4789.      able  Wordstar-type  editor.   Code  size  and speed seem to be roughly
  4790.      comparable  to  QuickBASIC  (better or worse depending on the program).
  4791.      Turbo BASIC's main fault seems to be that it lacks an assembly language
  4792.      interface--  it  uses  a  machine-language  INLINE  format like that in
  4793.      Turbo  Pascal.  This is going to make it an extreme nuisance to convert
  4794.      ADVBAS  for  use  with Turbo BASIC, but such is life.  In general, this
  4795.      is  at  least  as  strong  a  product as Microsoft's QuickBASIC, and it
  4796.      looks like we're shaping up for some fine marketing battles.
  4797.  
  4798.  
  4799.      Notes on Microsoft QuickBASIC v3.0, due out around April '87:
  4800.  
  4801.           The  major change here appears to be the addition of 8087 support.
  4802.      I haven't been able to find out anything further about this 'un.
  4803.  
  4804.  
  4805.  
  4806.  
  4807.  
  4808.  
  4809.  
  4810.  
  4811.  
  4812.  
  4813.  
  4814.  
  4815.  
  4816.  
  4817.  
  4818.  
  4819.  
  4820.  
  4821.  
  4822.  
  4823.  
  4824.  
  4825.  
  4826.  
  4827.  
  4828.  
  4829.  
  4830.  
  4831.  
  4832.  
  4833.  
  4834.  
  4835.  
  4836.                                    BASIC Bugs
  4837.  
  4838.  
  4839.  
  4840.  
  4841.           This  is  a  peculiar  one... it seems that BASIC can create files
  4842.      having  names  which  contain blank spaces.  This is a problem, because
  4843.      DOS  considers  the  space  to  be  a delimiter, and thus cannot handle
  4844.      these files.  Such files will not be listed correctly in the directory,
  4845.      and  will  be  impossible  to  manipulate from DOS (can't read, delete,
  4846.      or  otherwise  handle  the  file).  So, be careful to screen out spaces
  4847.      when  creating files from BASIC!  This caveat also applies to subdirec-
  4848.      tories, including those created with the MAKESUB routine of ADVBAS.
  4849.  
  4850.  
  4851.  
  4852.      Call for help:
  4853.  
  4854.           If  you  find  any other bugs in any IBM/Microsoft BASIC compiler,
  4855.      or  in  ADVBAS  for  that  matter,  please let me know.  If I can't fix
  4856.      it, at least I can warn people!
  4857.  
  4858.  
  4859.  
  4860.  
  4861.  
  4862.  
  4863.  
  4864.  
  4865.  
  4866.  
  4867.  
  4868.  
  4869.  
  4870.  
  4871.  
  4872.  
  4873.  
  4874.  
  4875.  
  4876.  
  4877.  
  4878.  
  4879.  
  4880.  
  4881.  
  4882.  
  4883.  
  4884.  
  4885.  
  4886.  
  4887.  
  4888.  
  4889.  
  4890.  
  4891.  
  4892.  
  4893.  
  4894.  
  4895.  
  4896.